+ (SID_DESC = + (SID_NAME = PLSExtProc) + (ORACLE_HOME = /ora8/m01/app/oracle/product/8.1.6) + (ENVS = LD_LIBRARY_PATH=/ora8/m01/app/oracle/product/8.1.6/lib:/usr/lib:/lib:/usr/openwin/lib:/ora8/m01/app/oracle/product/8.1.6/ctx/lib) + (PROGRAM = extproc) + ) ++ +
If your searches are still failing even after following these +instructions, try a simple test case to +determine whether the problem has something to do with the content +repository data model itself.
+ ++karlg@arsdigita.com
+Last revised: $Id$ + + + + + + + Index: openacs-4/packages/acs-content-repository/www/doc/intermedia.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/intermedia.html,v diff -u -r1.1.1.1 -r1.1.1.1.30.1 --- openacs-4/packages/acs-content-repository/www/doc/intermedia.html 13 Mar 2001 22:59:26 -0000 1.1.1.1 +++ openacs-4/packages/acs-content-repository/www/doc/intermedia.html 22 Jun 2016 07:40:41 -0000 1.1.1.1.30.1 @@ -1,104 +1,104 @@ - - -
Testing Intermedia
- Content Repository -- -
Even if you follow the instructions in the installation notes, content searches may -inexplicably fail to work. This document describes how to create a -simple test case independent of the content repository to verify that -Intermedia is indeed functioning properly.
- -Create a document table
- -Create a simple table to hold some test documents:
- -create table cr_test_documents ( - doc_id integer primary key, - author varchar2(30), - format varchar2(30), - title varchar2(256), - doc blob -);- -
Create an Intermedia preference to specify INSO filtering:
- -begin - ctx_ddl.create_preference - ( - preference_name => 'CONTENT_FILTER_PREF', - object_name => 'INSO_FILTER' - );- -
If this preference has already been created, this step will cause an -error that you can ignore.
- -Create an Intermedia index on the test table with INSO filtering:
- -create index cr_test_documents_idx on cr_test_documents ( doc )
- indextype is ctxsys.context
- parameters ('FILTER content_filter_pref' );
-
-Load test documents
- -You can use SQL*Loader to load some documents into the test table. -First create a control file named cr-test-docs.ctl: - -
load data -INFILE 'cr-test-docs.data' -INTO TABLE cr_test_documents -APPEND -FIELDS TERMINATED BY ',' -(doc_id SEQUENCE (MAX,1), - format, - title, - ext_fname FILLER CHAR(80), - doc LOBFILE(ext_fname) TERMINATED BY EOF)- -
Copy any number of documents (Microsoft Word, PDF, text, HTML, -etc.) to the file system of your database server. Create a data file -with an entry for each document you would like to load. This is -simply a comma-separated text file:
- -word, Simple Story,sample-docs/simple.doc, -excel, Simple Spreadsheet,sample-docs/simple.xls- -
Load the documents from the command line:
- -$ sqlldr userid=cms/cms control=cr-test-docs.ctl log=cr-test-docs.log - -SQL*Loader: Release 8.1.6.2.0 - Production on Thu Nov 9 13:36:56 2000 - -(c) Copyright 1999 Oracle Corporation. All rights reserved. - -Commit point reached - logical record count 2- -
Test search
- -Once the documents have been loaded, rebuild the index and run some -test queries:
- -
-SQL> alter index cr_test_documents_index rebuild online parameters ('sync');
-SQL> select score(1), doc_id from cr_test_documents
- where contains(doc, 'cars', 1) > 0;
-
- SCORE(1) DOC_ID
----------- ----------
- 4 1
-
-
--karlg@arsdigita.com
-Last revised: $Id$ - - - - - - - + + +
Testing Intermedia
+ Content Repository ++ +
Even if you follow the instructions in the installation notes, content searches may +inexplicably fail to work. This document describes how to create a +simple test case independent of the content repository to verify that +Intermedia is indeed functioning properly.
+ +Create a document table
+ +Create a simple table to hold some test documents:
+ +create table cr_test_documents ( + doc_id integer primary key, + author varchar2(30), + format varchar2(30), + title varchar2(256), + doc blob +);+ +
Create an Intermedia preference to specify INSO filtering:
+ +begin + ctx_ddl.create_preference + ( + preference_name => 'CONTENT_FILTER_PREF', + object_name => 'INSO_FILTER' + );+ +
If this preference has already been created, this step will cause an +error that you can ignore.
+ +Create an Intermedia index on the test table with INSO filtering:
+ +create index cr_test_documents_idx on cr_test_documents ( doc )
+ indextype is ctxsys.context
+ parameters ('FILTER content_filter_pref' );
+
+Load test documents
+ +You can use SQL*Loader to load some documents into the test table. +First create a control file named cr-test-docs.ctl: + +
load data +INFILE 'cr-test-docs.data' +INTO TABLE cr_test_documents +APPEND +FIELDS TERMINATED BY ',' +(doc_id SEQUENCE (MAX,1), + format, + title, + ext_fname FILLER CHAR(80), + doc LOBFILE(ext_fname) TERMINATED BY EOF)+ +
Copy any number of documents (Microsoft Word, PDF, text, HTML, +etc.) to the file system of your database server. Create a data file +with an entry for each document you would like to load. This is +simply a comma-separated text file:
+ +word, Simple Story,sample-docs/simple.doc, +excel, Simple Spreadsheet,sample-docs/simple.xls+ +
Load the documents from the command line:
+ +$ sqlldr userid=cms/cms control=cr-test-docs.ctl log=cr-test-docs.log + +SQL*Loader: Release 8.1.6.2.0 - Production on Thu Nov 9 13:36:56 2000 + +(c) Copyright 1999 Oracle Corporation. All rights reserved. + +Commit point reached - logical record count 2+ +
Test search
+ +Once the documents have been loaded, rebuild the index and run some +test queries:
+ +
+SQL> alter index cr_test_documents_index rebuild online parameters ('sync');
+SQL> select score(1), doc_id from cr_test_documents
+ where contains(doc, 'cars', 1) > 0;
+
+ SCORE(1) DOC_ID
+---------- ----------
+ 4 1
+
+
++karlg@arsdigita.com
+Last revised: $Id$ + + + + + + + Index: openacs-4/packages/acs-content-repository/www/doc/object-model.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/object-model.html,v diff -u -r1.1.1.1 -r1.1.1.1.30.1 --- openacs-4/packages/acs-content-repository/www/doc/object-model.html 13 Mar 2001 22:59:26 -0000 1.1.1.1 +++ openacs-4/packages/acs-content-repository/www/doc/object-model.html 22 Jun 2016 07:40:41 -0000 1.1.1.1.30.1 @@ -1,46 +1,46 @@ - - -
Object Model
- Content Repository -- -
The content repository is an extension of the ACS Object Model. -The following diagram illustrates the relationship among the -standard object types defined by the content repository (click on -a box to view a description and API summary for a particular object -type):
- -
-
-
-Note that content revisions and content items inherit separately -from the root of the object model. Each item may be related to one or -more revisions, but they are fundamentally different types of -objects.
- -Also important to note is the relationship between custom content types -and the rest of the object model. You define new content types as -subtypes of Content Revision, not of Content Item. This is because -new content types are characterized by their attributes, -which are stored at the revision level to make changes easy to -audit. Custom content types typically do not require additional -unaudited attributes or methods beyond those already provided by -the Content Item type. It is thereful almost never necessary to -create a custom subtype of Content Item itself.
- --karlg@arsdigita.com
+ + +
Object Model
+ Content Repository ++ +
The content repository is an extension of the ACS Object Model. +The following diagram illustrates the relationship among the +standard object types defined by the content repository (click on +a box to view a description and API summary for a particular object +type):
+ +
+
+
+Note that content revisions and content items inherit separately +from the root of the object model. Each item may be related to one or +more revisions, but they are fundamentally different types of +objects.
+ +Also important to note is the relationship between custom content types +and the rest of the object model. You define new content types as +subtypes of Content Revision, not of Content Item. This is because +new content types are characterized by their attributes, +which are stored at the revision level to make changes easy to +audit. Custom content types typically do not require additional +unaudited attributes or methods beyond those already provided by +the Content Item type. It is thereful almost never necessary to +create a custom subtype of Content Item itself.
+ ++karlg@arsdigita.com
Last revised: $Id$ \ No newline at end of file Index: openacs-4/packages/acs-content-repository/www/doc/requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/requirements.html,v diff -u -r1.2 -r1.2.22.1 --- openacs-4/packages/acs-content-repository/www/doc/requirements.html 11 Dec 2003 21:39:47 -0000 1.2 +++ openacs-4/packages/acs-content-repository/www/doc/requirements.html 22 Jun 2016 07:40:41 -0000 1.2.22.1 @@ -7,21 +7,21 @@ Karl Goldstein (karlg@arsdigita.com)
-Revision History +Revision History
VI.A Requirements: Data Model
- +The content repository must be able to store objects in any format, both text and binary. MIME types provide a standard set of codes for identifying the file format of each content item. For the purpose of data integrity, the repository must have a canonical list of MIME types that may be assigned to content items.
- +A content type is characterized by a set of attributes that may be associated with a text or binary content object. @@ -35,43 +35,43 @@
-- +10.10 Content types must be associated with unique keyword -identifiers, such as press_release, so they can be referenced +
10.10 Content types must be associated with unique keyword +identifiers, such as press_release, so they can be referenced in data tables, queries and procedural code.
-10.20 Content types must be associated with singular and -plural descriptive labels, such as Press Release and Press -Releases, to simplify user recognition.
+10.20 Content types must be associated with singular and +plural descriptive labels, such as Press Release and Press +Releases, to simplify user recognition.
-10.20 Content types may specify any number of attributes. +
10.20 Content types may specify any number of attributes. Attribute values are simple strings or numbers.
-10.30 Content types may inherit attributes from any other +
10.30 Content types may inherit attributes from any other other content type. For example, a regional press release may be a subtype of the press release type. Regional press releases have a -region attribute in addition to the characteristics of a +region attribute in addition to the characteristics of a regular press release.
-10.40 Part of the definition of a content type may include a +
10.40 Part of the definition of a content type may include a description of the parent-child relationships allowed for items of -this type. For example, a Press Release may contain one or -more items of type Image, but it should not contain any items -of type Internal Financial Status Report.
+this type. For example, a Press Release may contain one or +more items of type Image, but it should not contain any items +of type Internal Financial Status Report. -10.60 A content type definition may include a list of +
10.60 A content type definition may include a list of allowed file MIME types for items of this type.
-10.70 A content type definition may include a list of +
10.70 A content type definition may include a list of tokens to identify or flag relationships with other items. For example, the content type definition for a chapter of a reference manual may -include the tokens next, previous and see_also. +include the tokens next, previous and see_also. Each type of relationship may include a minimum and/or maximum number of relationships of this type that are required for an item to be published.
Items are the fundamental building blocks of the content repository. Each item represents a distinct text or binary content @@ -85,13 +85,13 @@
-- +20.10 Content items must have a simple unique identifier so they +
20.10 Content items must have a simple unique identifier so they can be related to other objects in the system. -
20.20 Each content item consists of a set of attributes and a +
20.20 Each content item consists of a set of attributes and a single text or binary object. -
20.25 All content items are associated with a few basic attributes +
20.25 All content items are associated with a few basic attributes to facilitate searching and development of browser interfaces to the content repository:
@@ -106,123 +106,123 @@ -20.30 Each content item must be an instance of a particular -content type. The content type defines the +
20.30 Each content item must be an instance of a particular +content type. The content type defines the attributes associated with the content item, in addition to the basic ones described above.
-20.40 A content item must have a unique, persistent URL +
20.40 A content item must have a unique, persistent URL (Uniform Resource Locator) by which it is publicly accessible, such as -/press-releases/products/widget. To facilitate moving of +/press-releases/products/widget. To facilitate moving of items within the repository, the item itself should only be associated -with the "tail" of the url, such as widget. The absolute URL +with the "tail" of the url, such as widget. The absolute URL of the item is determined by its location within the repository (See Content Organization).
-20.50 It must be possible to specify the language of each item.
+20.50 It must be possible to specify the language of each item.
-20.60 It must be possible to maintain a revision history for +
20.60 It must be possible to maintain a revision history for both the attributes and the text or binary object associated with a content item.
-20.70. There must be a flexible mechanism for implementing +
20.70. There must be a flexible mechanism for implementing access control on individual items, based on granting of permissions to groups or individual users.
-20.80. A content item may be associated with any number +
20.80. A content item may be associated with any number of workflows.
-20.90. Content items may themselves be "containers" or -"parents" for other content items. For example, an Article may -contain multiple Sections.
+20.90. Content items may themselves be "containers" or +"parents" for other content items. For example, an Article may +contain multiple Sections.
-20.95 Each item may be associated with any number of +
20.95 Each item may be associated with any number of related objects. The type and number of relationships must be constrained by the content type of the item (See 10.70 above).
As mentioned above, each content item may be associated with any number of revisions. The data model for revisions must support the following:
--30.10. A revision consists of the complete state of the item +
30.10. A revision consists of the complete state of the item as it existed at a certain point in time. This includes the main text or binary object associated with the item, as well as all attributes.
-30.20. The data model must be extensible so that revisions +
30.20. The data model must be extensible so that revisions for all content types (with any number of attributes) may be stored and retrieved efficiently.
40.0 Organization of the Repository
+40.0 Organization of the Repository
-- +40.10. The data model must support the hierarchical +
40.10. The data model must support the hierarchical organization of content items in a manner similar to a file system.
-40.20. The URL of a content item should reflect its location +
40.20. The URL of a content item should reflect its location in the hierarchy. For example, a press release with the URL -/press-releases/products/new-widget is located at the third +/press-releases/products/new-widget is located at the third level down from the root of the hierarchy.
- +A folder is analogous to a folder or directory in a file system. It represents a level in the content item hierarchy. In the -previous example, press-releases is a folder under the -repository root, and products is folder within that. The +previous example, press-releases is a folder under the +repository root, and products is folder within that. The description of a folder may include the following information:
--40.20.5.10. A URL-encoded name for building the path to +
40.20.5.10. A URL-encoded name for building the path to folders and individual items within the folder.
-40.20.5.20. A pointer to a content item that may serve as the +
40.20.5.20. A pointer to a content item that may serve as the "index" for the folder (i.e. the item that is served when the URL of the folder itself is accessed).
-40.20.5.30. A set of constraints on the number and type of +
40.20.5.30. A set of constraints on the number and type of content items that may be stored in the folder.
40.30. It must be possible to create symbolic links or +
40.30. It must be possible to create symbolic links or shortcuts to content items, so they may be presented at more than one URL or branch of the hierarchy.
-40.30.5 Content Symbolic Link.
+40.30.5 Content Symbolic Link.
A symbolic link is analogous to a symlink, alias or shortcut in a file system. The description of a symbolic link must include the following information:
-40.30.5.10. A URL-encoded name for the symbolic link. As +
40.30.5.10. A URL-encoded name for the symbolic link. As for folders and items, this only represents the "tail" of the URL, with the full URL being determined by the folder in which the link is located.
-40.30.5.20. A pointer to a target item which the symbolic +
40.30.5.20. A pointer to a target item which the symbolic link references..
-40.30.5.30. A title or label, which may be different from +
40.30.5.30. A title or label, which may be different from the title or label of the target item.
The content repository should provide a means of storing and managing the templates that are merged with content items to render @@ -237,28 +237,28 @@
VI.B Requirements: Stored Procedure API
-100.10 MIME Types
+100.10 MIME Types
Since a MIME type is a required attribute of each content item, the repository must be capable of managing a list of recognized MIME types for ensuring appropriate delivery and storage of content.
-100.10.10. Register a MIME type -
100.10.20. Set the description of a MIME type -
100.10.30. Get the description of a MIME type -
100.10.40. Determine whether a MIME type is text or binary -
100.10.50. Get a list of registered MIME types -
100.10.60. Unregister a MIME type +
100.10.10. Register a MIME type +
100.10.20. Set the description of a MIME type +
100.10.30. Get the description of a MIME type +
100.10.40. Determine whether a MIME type is text or binary +
100.10.50. Get a list of registered MIME types +
100.10.60. Unregister a MIME type
It is important to note that the role of MIME types in the content repository is simply to describe the general file format of each content item. Neither the data model nor the API support the full range of allowed parameters for the general MIME types such as -text/plain.
+text/plain. -100.20 Locales
+100.20 Locales
The repository must have access to a list of recognized locales for the purpose of publishing content items in multiple languages and @@ -281,152 +281,152 @@
--100.20.10. Register a locale, including language, +
100.20.10. Register a locale, including language, territory and character set.
-100.20.20. Get the language of a specified locale.
+100.20.20. Get the language of a specified locale.
-100.20.10. Get the character set code of a specified +
100.20.10. Get the character set code of a specified locale using either Oracle or WETF/ISO/ANSI codes.
-100.20.30. Get the number, date and currency format of a +
100.20.30. Get the number, date and currency format of a specified locale.
-100.20.40. Convert a text content item to a specified +
100.20.40. Convert a text content item to a specified locale (character set).
-100.20.50. Get a list of registered locales.
+100.20.50. Get a list of registered locales.
-100.20.60. Unregister a locale.
+100.20.60. Unregister a locale.
100.30 Content Types
+100.30 Content Types
--100.30.10. Create a content type, optionally specifying that +
100.30.10. Create a content type, optionally specifying that it inherits the attributes of another content type. Multiple inheritance is not supported.
-100.30.20. Get and set the singular and plural proper names +
100.30.20. Get and set the singular and plural proper names for a content type.
-100.30.30. Create an attribute for a content type.
+100.30.30. Create an attribute for a content type.
-100.30.40. Register a content type as a container for another +
100.30.40. Register a content type as a container for another content type, optionally specifying a minimum and maximum count of live items.
-100.30.50. Register a content type as a container for another +
100.30.50. Register a content type as a container for another content type, optionally specifying a minimum and maximum count of live items.
-100.30.60. Register a set of tags or tokens for labeling +
100.30.60. Register a set of tags or tokens for labeling child items of an item of a particular content type.
-100.30.70. Register a template for use +
100.30.70. Register a template for use with a content type, optionally specifying a use context ("intranet", "extranet") which the template is appropriate to use.
-100.30.80. Register a particular type of workflow to +
100.30.80. Register a particular type of workflow to associate with items of this content type by default.
-100.30.90. Register a MIME type as valid for a content type. -For example, the Image content type may only allow GIF and JPEG +
100.30.90. Register a MIME type as valid for a content type. +For example, the Image content type may only allow GIF and JPEG file formats.
-100.30.95 Register a relationship with another type of object, +
100.30.95 Register a relationship with another type of object, specifying a token or name for the relationship type as well as a minimum and/or maximum number of relationships of this type that are required for the item to be published.
100.40 Content Items
+100.40 Content Items
--100.40.10. Create a new item, specifying a parent context or +
100.40.10. Create a new item, specifying a parent context or the root of the repository by default.
-100.40.15. Rename an item.
+100.40.15. Rename an item.
-100.40.17. Copy an item to another location in the repository.
+100.40.17. Copy an item to another location in the repository.
-100.40.20. Move an item to another location in the repository.
+100.40.20. Move an item to another location in the repository.
-100.40.30. Get the full path (ancestry of an item) up to the +
100.40.30. Get the full path (ancestry of an item) up to the root.
-100.40.35. Get the parent of an item.
+100.40.35. Get the parent of an item.
-100.40.40. Determine whether an item may have a child of +
100.40.40. Determine whether an item may have a child of a particular content type, based on the existing children of the item and the constraints on the content type.
-100.40.45. Label a child item with a tag or token, based on +
100.40.45. Label a child item with a tag or token, based on the set of tags registered for the content type of the container item.
-100.40.50. Get the children of an item.
+100.40.50. Get the children of an item.
-100.40.55. Get the children of an item by type or tag.
+100.40.55. Get the children of an item by type or tag.
-100.40.60. Establish a generic relationship between any +
100.40.60. Establish a generic relationship between any object and a content item, optionally specifying a relationship type.
-100.40.70. Create a revision.
+100.40.70. Create a revision.
-100.40.80. Mark a particular revision of an item as "live".
+100.40.80. Mark a particular revision of an item as "live".
-100.40.83. Specify a start and end time when an item should be available.
+100.40.83. Specify a start and end time when an item should be available.
-100.40.85. Clear the live revision attribute of an item, +
100.40.85. Clear the live revision attribute of an item, effectively removing it from public view. -
100.40.90. Get a list of revisions for an item, including +
100.40.90. Get a list of revisions for an item, including modifying user, date modified and comments. -
100.40.95. Revert to an older revision (create a new revision based +
100.40.95. Revert to an older revision (create a new revision based on an older revision).
100.50 Content Folders
+100.50 Content Folders
The repository should allow for hierarchical arrangement of content items in a manner similar to a file system. The API to meet this -general requirement focuses primarily on content +general requirement focuses primarily on content folders:
-@@ -441,23 +441,23 @@100.50.10. Create a folder for logical groups of +
100.50.10. Create a folder for logical groups of content items and other folders. The folder name becomes part of the distinguished URL of any items it contains. Folders may be created at the "root" or may be nested within other folders.
-100.50.20. Set a label and description for a folder.
+100.50.20. Set a label and description for a folder.
-100.50.30. Get the label and description for a folder.
+100.50.30. Get the label and description for a folder.
-100.50.40. Get a list of folders contained within a folder.
+100.50.40. Get a list of folders contained within a folder.
-100.50.50. Move a folder to another folder.
+100.50.50. Move a folder to another folder.
-100.50.60. Copy a folder to another folder.
+100.50.60. Copy a folder to another folder.
-100.50.70. Create a symbolic link to a folder from +
100.50.70. Create a symbolic link to a folder from within another folder. The contents of the folder should be accessible via the symbolic link as well as the regular path.
-100.50.80. Tag all live item revisions within a folder with a +
100.50.80. Tag all live item revisions within a folder with a common version descriptor (i.e. 'Version 1.0' or 'August 1 release'), for the purpose of versioning an entire branch of the site. Folder -objects themselves are not eligible for versioning, since they +objects themselves are not eligible for versioning, since they are solely containers and do not have any content other than the items they contain.
-100.50.90. Delete a folder if it is empty.
+100.50.90. Delete a folder if it is empty.
The repository must offer integration with a workflow package for managing the content production process.
-100.60 Categorization
+100.60 Categorization
The repository must support a common hierarchical taxonomy of subject classifications that may be applied to content items.
-@@ -480,7 +480,7 @@100.60.10. Create a new subject category.
+100.60.10. Create a new subject category.
-100.60.20. Create a new subject category as the child of +
100.60.20. Create a new subject category as the child of another subject category.
-100.60.30. Assign a subject category to a content item.
+100.60.30. Assign a subject category to a content item.
-100.60.40. Remove a subject category from an item.
+100.60.40. Remove a subject category from an item.
-100.60.50. Get the subject categories assigned to a content +
100.60.50. Get the subject categories assigned to a content item.
Revision History
-| Author | Date | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Get latest revision (Tcl) | set live_revision_id [db_exec_plsql get_live_revision {select content_item__get_live_revision(:item_id)}]
Index: openacs-4/packages/acs-content-repository/www/doc/uninstall.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/uninstall.html,v
diff -u -r1.1.1.1 -r1.1.1.1.30.1
--- openacs-4/packages/acs-content-repository/www/doc/uninstall.html 13 Mar 2001 22:59:26 -0000 1.1.1.1
+++ openacs-4/packages/acs-content-repository/www/doc/uninstall.html 22 Jun 2016 07:40:41 -0000 1.1.1.1.30.1
@@ -1,42 +1,42 @@
-
-
- Uninstalling the Content Repository- Content Repository -- - The content repository includes an uninstall script, -sql/content-drop.sql. This script does two things: - -
The uninstall script does not do the following: - -
Because of what the uninstall script does not do, it is only -appropriate for removing the content repository in preparation for -removing the entire ACS Objects data model. If you wish to -upgrade an existing installation and cannot afford to lose your data, -you must run an upgrade script rather than uninstalling the entire -data model. - --karlg@arsdigita.com + + + Uninstalling the Content Repository+ Content Repository ++ + The content repository includes an uninstall script, +sql/content-drop.sql. This script does two things: + +
The uninstall script does not do the following: + +
Because of what the uninstall script does not do, it is only +appropriate for removing the content repository in preparation for +removing the entire ACS Objects data model. If you wish to +upgrade an existing installation and cannot afford to lose your data, +you must run an upgrade script rather than uninstalling the entire +data model. + ++karlg@arsdigita.com Last revised: $Id$ \ No newline at end of file Index: openacs-4/packages/acs-content-repository/www/doc/api/content.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/api/content.html,v diff -u -r1.1.1.1.30.1 -r1.1.1.1.30.2 --- openacs-4/packages/acs-content-repository/www/doc/api/content.html 9 Jun 2016 08:21:01 -0000 1.1.1.1.30.1 +++ openacs-4/packages/acs-content-repository/www/doc/api/content.html 22 Jun 2016 07:40:41 -0000 1.1.1.1.30.2 @@ -1,139 +1,139 @@ - - - content--Content Repository : content - - -
- - -Last Modified: $Id$ - - - + + +content++Content Repository : content + + +
+ + +Last Modified: $Id$ + + + Index: openacs-4/packages/acs-content-repository/www/doc/api/extlink.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/api/extlink.html,v diff -u -r1.1.1.1.30.1 -r1.1.1.1.30.2 --- openacs-4/packages/acs-content-repository/www/doc/api/extlink.html 9 Jun 2016 08:21:01 -0000 1.1.1.1.30.1 +++ openacs-4/packages/acs-content-repository/www/doc/api/extlink.html 22 Jun 2016 07:40:41 -0000 1.1.1.1.30.2 @@ -1,203 +1,203 @@ - - -content_extlink--Content Repository : content_extlink - - -
- - - Overview-External links are references to content pages on other web sites. -They provide the basis for maintaining a hierarchy of "bookmarks" that may be managed in a manner analogous to other content items. -In particular, external links may be tagged with keywords and related to the site's own content items. - -- - Related Objects-See also: {content_item} -- - - API-
content_extlink++Content Repository : content_extlink + + +
+ + + Overview+External links are references to content pages on other web sites. +They provide the basis for maintaining a hierarchy of "bookmarks" that may be managed in a manner analogous to other content items. +In particular, external links may be tagged with keywords and related to the site's own content items. + ++ + Related Objects+See also: {content_item} ++ + + API+
content_folder--Content Repository : content_folder - - -
- - - Overview-Content folders contain related content items and allow content managers to group content as they see fit. -Within a content folder, content items must have unique names since this is where they will be served from. -For example within the folder "movies" (served from "/movies") all items must have unique names, such as: -"terminator," "terminator2" (served from "/movies/terminator, "/movies/terminator2" respectively). - -- - Related Objects-See also: Content Item -- - - API-
- - -Last Modified: $Id$ - - - + + + content_folder++Content Repository : content_folder + + +
+ + + Overview+Content folders contain related content items and allow content managers to group content as they see fit. +Within a content folder, content items must have unique names since this is where they will be served from. +For example within the folder "movies" (served from "/movies") all items must have unique names, such as: +"terminator," "terminator2" (served from "/movies/terminator, "/movies/terminator2" respectively). + ++ + Related Objects+See also: Content Item ++ + + API+
+ + +Last Modified: $Id$ + + + Index: openacs-4/packages/acs-content-repository/www/doc/api/item.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/api/item.html,v diff -u -r1.3.18.1 -r1.3.18.2 --- openacs-4/packages/acs-content-repository/www/doc/api/item.html 9 Jun 2016 08:21:01 -0000 1.3.18.1 +++ openacs-4/packages/acs-content-repository/www/doc/api/item.html 22 Jun 2016 07:40:41 -0000 1.3.18.2 @@ -1,1394 +1,1394 @@ - - - content_item--Content Repository : content_item - - -
- - - Overview--Content items store the overview of the content published on a -website. The actual content is stored in content revisions. It is -implemented this way so that there can be mulitple versions of the -actual content while the main idea remains constant. For example: If -there is a review for the movie "Terminator," there will exist a -content item by the name "terminator" with all the right parameters -(supertype, parent, etc), there will also exist at least one content -revision pointing to this item with the actual review content. - -- - Related Objects-See also: content_revision, content_folder -- - - API-
- - -Last Modified: $Id$ - - - + + + content_item++Content Repository : content_item + + +
+ + + Overview++Content items store the overview of the content published on a +website. The actual content is stored in content revisions. It is +implemented this way so that there can be mulitple versions of the +actual content while the main idea remains constant. For example: If +there is a review for the movie "Terminator," there will exist a +content item by the name "terminator" with all the right parameters +(supertype, parent, etc), there will also exist at least one content +revision pointing to this item with the actual review content. + ++ + Related Objects+See also: content_revision, content_folder ++ + + API+
+ + +Last Modified: $Id$ + + + Index: openacs-4/packages/acs-content-repository/www/doc/api/keyword.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/api/keyword.html,v diff -u -r1.1.1.1.30.1 -r1.1.1.1.30.2 --- openacs-4/packages/acs-content-repository/www/doc/api/keyword.html 9 Jun 2016 08:21:01 -0000 1.1.1.1.30.1 +++ openacs-4/packages/acs-content-repository/www/doc/api/keyword.html 22 Jun 2016 07:40:41 -0000 1.1.1.1.30.2 @@ -1,569 +1,569 @@ - - - content_keyword--Content Repository : content_keyword - - -
- - - Overview-Keyword cassify a content_item. For example: If you have some press releases about dogs. -You might want assigning the Keyword dog to every single content_item. - -- - Related Objects-See also: content_item -- - - API-
- - -Last Modified: $Id$ - - - + + + content_keyword++Content Repository : content_keyword + + +
+ + + Overview+Keyword cassify a content_item. For example: If you have some press releases about dogs. +You might want assigning the Keyword dog to every single content_item. + ++ + Related Objects+See also: content_item ++ + + API+
+ + +Last Modified: $Id$ + + + Index: openacs-4/packages/acs-content-repository/www/doc/api/permission.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/api/permission.html,v diff -u -r1.1.1.1.30.1 -r1.1.1.1.30.2 --- openacs-4/packages/acs-content-repository/www/doc/api/permission.html 9 Jun 2016 08:21:01 -0000 1.1.1.1.30.1 +++ openacs-4/packages/acs-content-repository/www/doc/api/permission.html 22 Jun 2016 07:40:41 -0000 1.1.1.1.30.2 @@ -1,462 +1,462 @@ - - - content_permission--Content Repository : content_permission - - -
- - - Overview-Permissions can be set to allow certain users certain things. -- They can be compared with the Unix filesystem permission: read, write ... - -- - Related Objects-See also: {content_item - -} -- - - API-
- - -Last Modified: $Id$ - - - + + + content_permission++Content Repository : content_permission + + +
+ + + Overview+Permissions can be set to allow certain users certain things. +- They can be compared with the Unix filesystem permission: read, write ... + ++ + Related Objects+See also: {content_item + +} ++ + + API+
+ + +Last Modified: $Id$ + + + Index: openacs-4/packages/acs-content-repository/www/doc/api/revision.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/api/revision.html,v diff -u -r1.1.1.1.30.1 -r1.1.1.1.30.2 --- openacs-4/packages/acs-content-repository/www/doc/api/revision.html 9 Jun 2016 08:21:01 -0000 1.1.1.1.30.1 +++ openacs-4/packages/acs-content-repository/www/doc/api/revision.html 22 Jun 2016 07:40:41 -0000 1.1.1.1.30.2 @@ -1,488 +1,488 @@ - - - content_revision--Content Repository : content_revision - - -
- - - Overview-Content revisions contain the data for content items. -There is a many to one relationship between content revisions and content items. -There is at most one "live" revision for every content item though. -For example, there may be 5 revisions of the review for the movie "Terminator," -yet only one of these may be live on the website at a given time. - -- - Related Objects-See also: {content_item - -} -- - - API-
- -Last Modified: $Id$ - - - + + + content_revision++Content Repository : content_revision + + +
+ + + Overview+Content revisions contain the data for content items. +There is a many to one relationship between content revisions and content items. +There is at most one "live" revision for every content item though. +For example, there may be 5 revisions of the review for the movie "Terminator," +yet only one of these may be live on the website at a given time. + ++ + Related Objects+See also: {content_item + +} ++ + + API+
+ +Last Modified: $Id$ + + + Index: openacs-4/packages/acs-content-repository/www/doc/api/symlink.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/api/symlink.html,v diff -u -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-content-repository/www/doc/api/symlink.html 9 Jun 2016 08:21:01 -0000 1.2.2.1 +++ openacs-4/packages/acs-content-repository/www/doc/api/symlink.html 22 Jun 2016 07:40:41 -0000 1.2.2.2 @@ -1,324 +1,324 @@ - - - content_symlink--Content Repository : content_symlink - - -
- - - Overview-Symlinks are pointers to items within the content repository. -They are simply used to create links between content items. - -- - Related Objects-See also: content_item, content_folder -- - - API-
- - -Last Modified: $Id$ - - - + + + content_symlink++Content Repository : content_symlink + + +
+ + + Overview+Symlinks are pointers to items within the content repository. +They are simply used to create links between content items. + ++ + Related Objects+See also: content_item, content_folder ++ + + API+
+ + +Last Modified: $Id$ + + + Index: openacs-4/packages/acs-content-repository/www/doc/api/template.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/api/template.html,v diff -u -r1.1.1.1.30.1 -r1.1.1.1.30.2 --- openacs-4/packages/acs-content-repository/www/doc/api/template.html 9 Jun 2016 08:21:01 -0000 1.1.1.1.30.1 +++ openacs-4/packages/acs-content-repository/www/doc/api/template.html 22 Jun 2016 07:40:41 -0000 1.1.1.1.30.2 @@ -1,266 +1,266 @@ - - - content_template--Content Repository : content_template - - -
- - - Overview-Templates are a special class of text objects that are used for specifying the layout of a content item. -They may be mapped to content types, meaning that every item of that type will display using that template -unless a specific item overrides the default by mapping to a template itself. - -- - Related Objects-See also: content_item, content_folder -- - - API-
content_template++Content Repository : content_template + + +
+ + + Overview+Templates are a special class of text objects that are used for specifying the layout of a content item. +They may be mapped to content types, meaning that every item of that type will display using that template +unless a specific item overrides the default by mapping to a template itself. + ++ + Related Objects+See also: content_item, content_folder ++ + + API+
content_type--Content Repository : content_type - - -
- - - Overview-This package is used to manipulate content types and attributes -Content types represent the different kind of content displayed on a website. -All content items should subclass a content type. - -- - Related Objects-See also: {Content Item - -} -- - - API-
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+
+-Test 5 +Test 5
Verify the results of localization routines.
Index: openacs-4/packages/acs-lang/www/admin/test/timezone.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-lang/www/admin/test/Attic/timezone.adp,v diff -u -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-lang/www/admin/test/timezone.adp 16 Jun 2015 09:13:28 -0000 1.2 +++ openacs-4/packages/acs-lang/www/admin/test/timezone.adp 22 Jun 2016 07:45:44 -0000 1.2.2.1 @@ -8,7 +8,7 @@
-Test 3 +Test 3
Verify that data required to convert from local times for Europe/Paris into Universal Time is loaded into the database. @@ -22,7 +22,7 @@
-Test 4 +Test 4
Verify that the conversions between UTC and local time work correctly.
Index: openacs-4/packages/acs-lang/www/doc/i18n-design.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-lang/www/doc/i18n-design.adp,v diff -u -r1.1.2.3 -r1.1.2.4 --- openacs-4/packages/acs-lang/www/doc/i18n-design.adp 9 Jun 2016 13:03:12 -0000 1.1.2.3 +++ openacs-4/packages/acs-lang/www/doc/i18n-design.adp 22 Jun 2016 07:45:44 -0000 1.1.2.4 @@ -37,7 +37,7 @@ possible, as well as the same message catalogs and format strings should be a strong goal.
A set of unit tests are included in the acs-lang +
A set of unit tests are included in the acs-lang package, to allow automatic testing after installation.
Examples are
-en_US English US+en_US English US
ja_JP Japanese
fr_FR France French.
ja_JP Japanese
fr_FR France French.
The i18n module figures out the locale for a current request -makes it accessible via the ad_locale function:
+makes it accessible via the ad_locale function:[ad_locale user locale ] => fr_FR @@ -79,10 +79,10 @@ It has not yet been decided how the user's preferred locale will be initialized. For now, there is a site wide default package -parameter [parameter::get -parameter DefaultLocale -default -"en_US"] +parameter [parameter::get -parameter DefaultLocale -default +"en_US"] , and an API for setting the locale with the -preference stored in a session variable: The ad_locale_set +preference stored in a session variable: The ad_locale_set function is used to set the user's preferred locale to a desired value. It saves the value in the current session. @@ -99,7 +99,7 @@ The request processor should use the ad_locale API to figure out the preferred locale for a request (perhaps combining user preference with subsite defaults in some way). It will make this -information accesible via the ad_conn +information accesible via the ad_conn function:ad_conn localeCharacter Sets and Encodings
@@ -111,7 +111,7 @@ Content-Type: text/html; charset=iso-8859-1
You can obtain the preferred character set for a locale via the -ad_locale API shown below:
+ad_locale API shown below:set locale "en_US" [ad_locale charset $locale @@ -135,13 +135,13 @@
- Separate template for each target language
Have a copy of each template file in each language you support, -e.g., foo.en.adp, foo.fr.adp, -foo.de.adp, etc.
We will refer to this style of template pages as +e.g., foo.en.adp, foo.fr.adp, +foo.de.adp, etc.
We will refer to this style of template pages as language-specific templates.
- A single template file for multiple languages
You write your template to contain references to translation strings either from data sources or using <TRN> tags.
For example, a site might support multiple languages, but use a -single file foo.adp which contains no language-specific +single file foo.adp which contains no language-specific content, and would only make use of data sources or <TRN> tags which in turn use the message catalog to look up language-specific content.
We will refer to this style of page as a multilingual @@ -157,14 +157,14 @@ template source page to handle all the languages, and to have all language-dependent strings be looked in a message catalog. We can do this either by creating data sources which call -lang_message_lookup, or else use the <TRN> tag to do +lang_message_lookup, or else use the <TRN> tag to do the same thing from within an ADP file.
Caching multilingual ADP Templates
Message catalog lookups can be potentially expensive, if many of them are done in a page. The templating system can already precompile and and cache adp pages. This works fine for a page in a -specific language such as foo.en.adp +specific language such as foo.en.adp , but we need to modify the caching mechanism if we want to use a single template file to target multiple languages. @@ -175,13 +175,13 @@-If the user requests the page foo +If the user requests the page foo , and their ad_locale is "en_US" then effective locale @@ -205,7 +205,7 @@ obtain the preferred locale for a page request, and will attempt to find a template file which most closely matches that locale.<master> <trn key=username_prompt>Please enter your username</tr> -<input type=text name=username> +<input type="text" name=username> <p> <trn key=password_prompt>Enter Password:</trn> <input type=password name=passwd>We will use the following convention for naming template files: -filename.locale_or_language.adp.
+filename.locale_or_language.adp.Examples:
foo.en_US.adp @@ -227,32 +227,32 @@The algorithm for finding the best matching template for a request in a given locale is given below:
-
- Find the desired target locale using [ad_conn locale] +
- Find the desired target locale using [ad_conn locale] NOTE: This will always be a specific Locale (i.e., language_COUNTRY)
- Look for a template file whose locale suffix matches exactly.
For example, if the filename in the URL request is simply -foo and [ad_conn locale] returns en_US then look -for a file named foo.en_US.adp.
+foo and [ad_conn locale] returns en_US then look +for a file named foo.en_US.adp.- If an exact match is not found, look for template files whose name matches the language portion of the target locale. -
For example, if the URL request name is foo and -[ad_conn locale] returns en_US and a file named -foo.en_US.adp is not found, then look for all templates +
For example, if the URL request name is foo and +[ad_conn locale] returns en_US and a file named +foo.en_US.adp is not found, then look for all templates matching "en_*" as well as any template which just has the "en" suffix.
So for example if the user's locale en_GB and the following -files exist:
foo.en_US.adp
then use foo.en_US.adp -
If however both foo.en_US.adp and foo.en.adp -exist, then use foo.en.adp preferentially, i.e., +files exist:
foo.en_US.adp
then use foo.en_US.adp +
If however both foo.en_US.adp and foo.en.adp +exist, then use foo.en.adp preferentially, i.e., don't switch locales if you can avoid it. The reasoning here is that people can be very touchy about switching locales, so if there is a generic matching language template available for a language, use it rather than using an incorrect locale-specific template.
- If no locale-specific template is found, look for a template matching just the language
I.e., if the request is for en_US, and there exists a file -foo.en.adp, use that.
+foo.en.adp, use that.- If no locale-specific template is found, look for a simple .adp -file, such as foo.adp.
+file, such as foo.adp.
Once a template file is found we must decide what character set it is authored in, so that we can correctly load it into Tcl (which @@ -266,12 +266,12 @@
So we make the convention that the template file is authored in it's effective locale's character set. For multilingual templates, we will load the template in the site default character -set as specified by the AOLserver OutputCharset +set as specified by the AOLserver OutputCharset initializatoin parameter. For now, we will say that authoring generic multilingual adp files can and should be done in ASCII. Eventually we can switch to using UTF8.
A character set corresponding to a locale can be found using the -[ad_locale charset$locale] command. The +[ad_locale charset$locale] command. The templating system should call this right after it computes the effective locale, so it can set up that charset encoding conversion before reading the template file from disk.
@@ -291,18 +291,18 @@ adp_parse_ad_locale user_file looks at the output headers, and if it sees a content type with an explicit charset, it passes it along to ns_return. -The default character set for a template .adp file +
The default character set for a template .adp file should be the default system encoding.
VI.C Loading Regular Tcl Script Files
10.50 By default, tcl and template files in the system will be loaded using the default system encoding. This is generally ISO-8859-1 for AOLserver running on Unix systems in English.This default can be overridden by setting the AOLserver init -parameter for the MIME type of .tcl files to include an +parameter for the MIME type of .tcl files to include an explcit character set. If an explicit MIME type is not found, -ns_encodingfortype will default to the AOLserver init -parameter value DefaultCharset if it is set.
+ns_encodingfortype will default to the AOLserver init +parameter value DefaultCharset if it is set.Example AOLserver .ini configuration file to set default script file and template file charset to ShiftJIS:
which will be stored with the full key of -bboard.alerts.mail_notification +bboard.alerts.mail_notification .@@ -356,7 +356,7 @@ Example: You are looking up the message string "Title" in the -notes +notes package.Is used to load the message catalogs for a package. The catalog -files are stored in a package subdirectory called catalog +files are stored in a package subdirectory called catalog . -Their file names have the form *.encoding.cat +Their file names have the form *.encoding.cat , where encoding is the name of a MIME charset encoding @@ -459,7 +459,7 @@[lang_message_lookup $locale notes.title "Title"] @@ -370,11 +370,11 @@-The string is looked up by the symbolic key notes.title +The string is looked up by the symbolic key notes.title -(or title +(or title for short), and the constant value -"Title" +"Title" is supplied as documentation and as a default value. Having a default value allows developers to code their application immediately without waiting to populate the message @@ -386,21 +386,21 @@ "title" in a page in the bboard package will actually reference the "bboard.title" entry in the message catalog.You can override this behavior by either using a fully qualified -key such as bboard.title or else by changing the message -catalog namespace using the lang_set_package command:
+key such as bboard.title or else by changing the message +catalog namespace using the lang_set_package command:[lang_set_package "bboard"]So for example code that runs in a scheduled proc, where there is not necessarily any concept of a "current package", would either use fully qualified keys to look up messages, or else call -lang_set_package +lang_set_package before doing a message lookup.Message Catalog Definition Files
A message catalog is defined by placing a file in the -catalog +catalog subdirectory of a package. Each file defines a set of messages in different locales, and the file is written in a character set specified by it's file suffix: @@ -433,9 +433,9 @@
Calling the Message Catalog API from inside of Templates
Index: openacs-4/packages/acs-lang/www/doc/i18n-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-lang/www/doc/i18n-design.html,v diff -u -r1.3 -r1.3.2.1 --- openacs-4/packages/acs-lang/www/doc/i18n-design.html 27 Oct 2014 16:39:40 -0000 1.3 +++ openacs-4/packages/acs-lang/www/doc/i18n-design.html 22 Jun 2016 07:45:44 -0000 1.3.2.1 @@ -1,852 +1,852 @@ - - -ACS 4 Globalization Detailed Design
by Henry Minsky -- - -
I. Essentials
When applicable, each of the following items should -receive its own link: --
-
-
- User directory: none -
- ACS administrator: acs-lang -
- Subsite administrator directory: none - -
- Tcl script directory: /api-doc -
- PL/SQL file: -
- Data model: - -
- Requirements document -
II. Introduction
- -- -
III. Historical Considerations
- -V. Design Tradeoffs
- --
-
- Performance: availability and efficiency
-
-For Internationalization to be effective, it needs to be -integrated into every module in the system. Thus making the overhead -as low as possible is a priority, otherwise developers will be reluctant -to use it in their code. -
-Wherever possible, caching in AOLserver shared memory is used -to remove the need to touch the database. Precompiling of template -files should reduce the overhead to zero in most cases for translation -message lookups. The amount of overhead added to the request processor -can be reduced by caching filesystem information on matching of template -files for locales. - -
- Flexibility -
- Interoperability
-
-
- Reliability and robustness
-
- -
- Usability
-
-
- Maintainability -
- Portability
-
-The ACS Tcl I18N APIs should be as close as possible to the ultimate Java -APIs. This means that using the same templates if possible, as well as the -same message catalogs and format strings should be a strong goal. - - -
- Reusability -
- Testability
-
-A set of unit tests are included in the acs-lang package, to -allow automatic testing after installation. - -
- -
VI. API
- -VI.A Locale API
- -10.30 - -A Locale object represents a specific geographical, political, or -cultural region. An operation that requires a Locale to perform its -task is called locale-sensitive and uses the Locale to tailor -information for the user. For example, displaying a number is a -locale-sensitive operation--the number should be formatted according -to the customs/conventions of the user's native country, region, or -culture. - --We will refer to a Locale by a combination of a language and country. -In the Java Locale API there is an optional variant which can be added to a locale, -which we will omit in the Tcl API. -
-
-The language is a valid ISO Language Code. These codes are the
-lower-case two-letter codes as defined by ISO-639. You can find a full
-list of these codes at a number of sites, such as:
-
-
-http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt
-
-The country is a valid ISO Country Code. These codes are the upper-case two-letter codes as defined by ISO-3166. You can find a full list of these codes at a number of sites, such as:
-
-http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html
-
- -Examples are
-en_US English US -- - -
- ja_JP Japanese
- fr_FR France French. -
-The i18n module figures out the locale for a current request -makes it accessible via the ad_locale function: -
-[ad_locale user locale] => fr_FR -[ad_locale subsite locale] => en_US -- -It has not yet been decided how the user's preferred locale will be -initialized. For now, there is a site wide default package parameter -[parameter::get -parameter DefaultLocale -default "en_US"], and an API for setting -the locale with the preference stored in a session variable: - -The ad_locale_set function is used to set the user's preferred locale -to a desired value. It saves the value in the current session. - -
- ad_locale_set locale "en_US" - will also automatically set [ad_locale user language] - ( to "en" in this case) - - ad_locale_set timezone "PST" - - -- -The request processor should use the ad_locale API to figure out the -preferred locale for a request (perhaps combining user preference with -subsite defaults in some way). It will make this information accesible -via the ad_conn function: - -
- ad_conn locale -- - -
- -
Character Sets and Encodings
- -We refer to MIME character set names which are the valid values -which can be passed in a MIME header, such as --Content-Type: text/html; charset=iso-8859-1 -- -
You can obtain the preferred character set for a locale via the - ad_locale API shown below: - -
- -
-set locale "en_US" -[ad_locale charset $locale] => "iso-8859-1" or "shift_jis" -- Returns a case-insensitive name of a MIME character set. -
- - -
-We already have an AOLserver function to convert a MIME charset name to a Tcl encoding name: -
-
-[ns_encodingforcharset "iso-8859-1"] => iso8859-1 -- -
- - -
Templating
- -The goal of templates is to separate program logic from data -presentation. --For presenting data in multiple languages, there are two basic ways to -use templates for a given abstract URL. Say we have the URL "foo", for example. -We can provide templates for it in the following ways: - -
-
-
- Separate template for each target language
-
Have a -copy of each template file in each language you support, e.g., -foo.en.adp, foo.fr.adp, foo.de.adp, etc. -
-We will refer to this style of template pages as language-specific templates. -
-
- A single template file for multiple languages
-
-You write your template to contain references to translation strings -either from data sources or using <TRN> tags. -
- For example, a site might support multiple languages, but use a -single file foo.adp which contains no language-specific -content, and would only make use of data sources or <TRN> tags -which in turn use the message catalog to look up language-specific content. -
-We will refer to this style of page as a multilingual template. - -
-
-But for a page which has a very fixed format, such as a data entry -form, it would mean a lot less redundant work to use a single template -source page to handle all the languages, and to have all -language-dependent strings be looked in a message catalog. We can do this either by -creating data sources which call lang_message_lookup, or else -use the <TRN> tag to do the same thing from within an ADP file. - -
- -
Caching multilingual ADP Templates
Message catalog lookups -can be potentially expensive, if many of them are done in a page. The -templating system can already precompile and and cache adp pages. -This works fine for a page in a specific language such as -foo.en.adp, but we need to modify the caching mechanism if we -want to use a single template file to target multiple languages. - -Computing the Effective Locale
- --Let's say you have a template file "foo.adp" and it contains calls to -look up message strings using the TRN tag: - -
-- -If the user requests the page foo, and their ad_locale -is "en_US" then effective locale is "en_US". Message lookups -are done using the effective locale. If the user's locale is "fr_FR", -then the effective locale will be "fr_FR". - --<master> -<trn key=username_prompt>Please enter your username</tr> -<input type=text name=username> -<p> -<trn key=password_prompt>Enter Password:</trn> -<input type=password name=passwd> --
- -If we evaluate the TRN tags at compile time then we need to associate -the effective locale in which the page was evaluated with the -cached compiled page code. -
- -The effective locale of a template page that has an explicit locale, -such as a file named "foo.en.adp" or "foo.en_US.adp", will be that -explicit locale. So for example, even if a user has a preferred locale -of "fr_FR", if there is only a page named "foo.en.adp", then that page -will be evaluated (and cached) with an effective locale of en_US. - -
- -
VI.B Naming of Template Files To Encode Language and Character Set
- -10.40 -The templating system will use the Locale API to obtain the preferred -locale for a page request, and will attempt to find a template file which -most closely matches that locale. --We will use the following convention for naming template files: -filename.locale_or_language.adp. - -
-Examples: -
---foo.en_US.adp -foo.en.adp - -foo.fr_FR.adp -foo.fr.adp - -foo.ja_JP.adp -foo.ja.adp - --
- - -The user request has a locale which is of the form -language_country. If someone wants English, they will -implicitly be choosing a default, such as en_US or en_GB. The default -locale for a language can be configured in the system locale -tables. So for example the default locale for "en" could be "en_US". -
- - - -The algorithm for finding the best matching template for a request in -a given locale is given below: - -
-
-
-
- Find the desired target locale using [ad_conn locale]
- NOTE: This will always be a specific Locale (i.e., language_COUNTRY)
-
-
-
- Look for a template file whose locale suffix matches exactly.
-
- For example, if the filename in the URL request is simply foo - and [ad_conn locale] returns en_US then look for a file - named foo.en_US.adp. - -
-
-
-If an exact match is not found, look for template files whose name
- matches the language portion of the target locale.
-
- - For example, if the URL request name is foo and [ad_conn locale] returns - en_US and a file named foo.en_US.adp is not found, then look for - all templates matching "en_*" as well as any template which just has the "en" suffix. - -
- So for example if the user's locale en_GB and the following files exist: - -
- foo.en_US.adp - -
- then use foo.en_US.adp -
- - If however both foo.en_US.adp and foo.en.adp -exist, then use foo.en.adp preferentially, i.e., don't -switch locales if you can avoid it. The reasoning here is that people -can be very touchy about switching locales, so if there is a generic -matching language template available for a language, use it rather -than using an incorrect locale-specific template. - - - -
-
-
-
- If no locale-specific template is found, look for a template matching
- just the language
-
- - I.e., if the request is for en_US, and there exists a file - foo.en.adp, use that. - - -
-
- - -If no locale-specific template is found, look for a simple .adp file, - such as foo.adp. -
-Once a template file is found we must decide what character set it is -authored in, so that we can correctly load it into Tcl (which converts it -to UTF8 internally). -
- -It would be simplest to mandate that all templates are authored in UTF8, but -that is just not a practical thing to enforce at this point, I believe. Many -designers and other people who actually author the HTML template files -will still find it easier to use legacy tools that author in their -"native" character sets, such as ShiftJIS in Japan, or BIG5 in China. -
- -So we make the convention that the template file is authored in it's -effective locale's character set. For multilingual templates, -we will load the template in the site default character set as -specified by the AOLserver OutputCharset initializatoin -parameter. For now, we will say that authoring generic multilingual -adp files can and should be done in ASCII. Eventually we can switch to -using UTF8. - -
-A character set corresponding to a locale can be found using the -[ad_locale charset $locale] command. The templating -system should call this right after it computes the effective locale, so it -can set up that charset encoding conversion before reading the template file from disk. -
- -We read the template file using this encoding, and set the default -output character set to it as well. Inside of either the .adp page or -the parent .tcl page, it is possible for the developer to issue a -command to override this default output character set. The way this -is done is currently to stick an explicit content-type header in -the AOLserver output headers, for example to force the output to ISO-8859-1, you -would do - - -
-ns_set put [ns_conn outputheaders] "content-type" "text/html; charset=iso-8859-1" -- - -
-design questionWe should have an API for this. The hack now is that the -adp handler adp_parse_ad_locale user_file looks at the output headers, and if it sees a content type with -an explicit charset, it passes it along to ns_return. -- - -
-The default character set for a template .adp file should -be the default system encoding. - -
- -
VI.C Loading Regular Tcl Script Files
- -10.50 By default, tcl and template files in the system will be -loaded using the default system encoding. This is generally ISO-8859-1 -for AOLserver running on Unix systems in English. --This default can be -overridden by setting the AOLserver init parameter for the MIME type -of .tcl files to include an explcit character set. If an explicit -MIME type is not found, ns_encodingfortype will default to the -AOLserver init parameter value DefaultCharset if it is set. -
- -Example AOLserver .ini configuration file to set default script file -and template file charset to ShiftJIS: - - -
-
-ns_section {ns/mimetypes }
-...
-ns_param .tcl {text/plain; charset=shift_jis}
-ns_param .adp {text/html; charset=shift_jis}
-
-ns_section ns/parameters
-...
-# charset hacking
-ns_param HackContentType 1
-ns_param URLCharset shift_jis
-ns_param OutputCharset shift_jis
-ns_param HttpOpenCharset shift_jis
-ns_param DefaultCharset shift_jis
-
-
-
-
-VI.A Message Catalog API
- -We want to use something like the Java ResourceBundle, where the -developer can declare a set of resources for a given namespace -and locale. - --For AOLserver/TCL, to make the message catalog more manageable, we will -split it into one message catalog per package, plus one default global -message namespace in case we need it. So for example, -
-Message lookups are done using a combination of a key string and a -locale or language, as well as an implicit package prefix on the key -string. The API for using the message catalog is as follows: -
- -
-- - -The locale arg can actually be a full locale, or else a simple language abbrev, such as fr, en, etc. - -The lookup rules for finding strings based on key and locale are tried -in order as follows: --lang_message_lookup locale key [default_string] -- -lang_message_lookupis abbreviated by the procedure named "_", -which is the convention used by the GNU strings message catalog package. --
-
-
-
- Lookup is first tried with the full locale (if present) and package.key - -
- Lookup is tried with just the language portion of the locale and - package.key - -
- Lookup is tried with the full locale and key without package prefix. - -
- Lookup is tried with language and key without package prefix. - -
-
-[lang_message_lookup $locale notes.title "Title"] - -can be abbreviated by -[_ $locale notes.title "Title"] - -# message key "title" is implicitly with respect to package key -# "notes", i.e., notes.title -[_ $locale title "Title"] - -- -The string is looked up by the symbolic key notes.title (or title for short), and the constant value "Title" is supplied as documentation and -as a default value. Having a default value allows developers to code their application -immediately without waiting to populate the message catalog. -
- -
Default Package Namespace
- -By default, keys are prefixed with the name of the current package (if -a page request is being processed). So a lookup of the key "title" in -a page in the bboard package will actually reference the -"bboard.title" entry in the message catalog. - --You can override this behavior by -either using a fully qualified key such as bboard.title or -else by changing the message catalog namespace using the -lang_set_package command: - -
-[lang_set_package "bboard"] -- -So for example code that runs in a scheduled proc, where there is not necessarily -any concept of a "current package", would either use fully qualified keys to -look up messages, or else call lang_set_package before doing a message lookup. - - - -
-
Message Catalog Definition Files
- -A message catalog is defined by placing a file in the catalog -subdirectory of a package. Each file defines a set of messages -in different locales, and the file is written in a character set -specified by it's file suffix: - --/packages/bboard/catalog/ - bboard.iso-8859-1 - bboard.shift_jis - bboard.iso-8859-6 -- - -A message catalog file consists of tcl code to define -messages in a given language or locale: - -
- -_mr en mail_notification "This is an email notification" -_mr fr mail_notification "Le notification du email" -... - -- - -In the example above, if the catalog file was loaded from the bboard -package, all of the keys would be prefixed autmatically with "
bboard.".
-
-Loading A Message Catalog At Package Init Time
- -The API function --lang_catalog_load package_key -- -Is used to load the message catalogs for a package. -The catalog files are stored in a package subdirectory called catalog. Their -file names have the form *.encoding.cat, where encoding -is the name of a MIME charset encoding (not a Tcl charset name as was used -in a previous version of this command). - -
-/packages/bboard/catalog - /main.iso8859-1.cat - /main.shift_jis.cat - /main.iso-8859-6.cat - /other.iso8859-1.cat - /other.shift_jis.cat - /other.iso-8859-6.cat -- - -
- -You can add more pseudo-levels of hierarchy in naming the message keys, using -any separator character you want, for example - -
--which will be stored with the full key of bboard.alerts.mail_notification. - --_mr fr alerts.mail_notification "Le notification du email" --
- -
Calling the Message Catalog API from inside of Templates
- -Inside of a template, you can always make a call to the message -catalog API via a Tcl escape: - --<%= [_ $locale bboard.passwordPrompt "Enter Password"]%> -- -However, this is awkward and ugly to use. We have defined an ADP tag -which invokes the message catalog lookup. As explained in the previous -section, since our system precompiles adp templates, we can get a -performance improvement if we can cache the message lookups at -template compile time. -
- -The <TRN> tag is a call to lang_message_lookup that can be used inside -of an ADP file. Here is the documention: - -
- Procedure that gets called when the <trn> tag is encountered on an ADP page. - The purpose of the procedure is to register the text string enclosed within a - pair of <trn> tags as a message in the catalog, and to display the appropriate - translated string. - Takes three optional parameters:- - - -lang,type- andkey. --
- Example 1: Display the text string Hello on an ADP page (i.e. do nothing special): -keyspecifies the key in the message catalog. If it is omitted - this procedure returns simply the text enclosed by the tags. -langspecifies the language of the text string enclosed within the - flags. If it is ommitted value defaults to English. -typespecifies the context in which the translation is made. If omitted, - type is user which means that the translation is provided in the user's preferred language. -staticspecifies that this tag should be translated once at templat compile time, rather than dynamically every time the page is run. This will be unneccessaru and will be deprecated once we -have implemented effective locale based cacheing for templates. -- <trn>Hello</trn> -- Example 2: Assign the key key hello to the text string Hello and display - the translated string in the user's preferred language: -- <trn key="hello">Hello</trn> -- Example 3: Specify that Bonjour needs to be registered as the French translation - for the key hello (in addition to displaying the translation in the user's - preferred language): -- <trn key="hello" lang="fr">Bonjour</trn> -- Example 4: Register the string and display it in the preferred language of the - current user. Note that the possible values for thetype- paramater are determined by what has been implemented in thead_localeprocedure. - By default, only theusertype is implemented. An example of a type that - could be implemented issubsite, - for displaying strings in the language of the subsite that owns the current web page. -- <trn key="hello" type="user">Hello</trn> -- -- Example 5: Translates the string once at template compile time, using the effective local of the page. - -
- <trn key="hello" static>Hello</trn> -- - - -
VII. Data Model Discussion
- -Internationalizing the Data Models
- -Some data which is stored in ACS package and core database tables may -be presented to users, and thus may need to be stored in multiple -languages. Examples of this are the descriptions of package or site -parameters in the administrative interface, the "pretty names" of -objects, and group names. - -- -Tables which are in acs kernel and have user-visible names that may -need to be translated in order to create an admin back end in another -language: - -
-user groups: - group_name - -acs_object_types: - pretty_name - pretty_plural - -acs_attributes: - pretty_name - pretty_plural - -acs_attribute_descriptions - description (clob) - -procedure add_description- add a lang arg ? - -acs_enum_values ? pretty_name - -acs_privileges: - pretty_name - pretty_plural - -apm_package_types - pretty_name - pretty_plural - - -apm_package "instance_name"? Maybe a given instance -gets instantiated with a name in the desired language? - - -apm_parameters: - parameter_name - section_name -- -One approach is to split a table into two tables, one holding -language-independent datam, and the other holding language-dependent -data. This approach was described in the ASJ Multilingual Site Article. -
-In that case, it is convenient to create a new view which looks like -the original table, with the addition of a language column that you -can specify in the queries. -
-
Drawbacks to Splitting Tables
- It is not totally transparent -to developers -Every query against the table which requests or -modifies language-dependent columns must now include a WHERE clause to -select the language. -
-Extra join may slow things down
The extra join of the two
-tables may cause queries to slow down, although I am not sure what the
-actual performance hit might be. It shouldn't be too large, because
-the join is against a fully indexed table.
-
-
- - -
VIII. User Interface
- -IX. Configuration/Parameters
- --
-
- -
- -
X. Code Examples
--
-
- fconfigure -encoding blah -
- content type in outputheaders set for encoding conversion
-
-
-ad_proc adp_parse_ad_conn_file {} { - handle a request for an adp and/or tcl file in the template system. -} { - namespace eval template variable parse_level "" - #ns_log debug "adp_parse_ad_conn_file => file '[file root [ad_conn file]]'" - set parsed_template [template::adp_parse [file root [ad_conn file]] {}] - db_release_unused_handles - if { $parsed_template ne ""} { - set content_type [ns_set iget [ns_conn outputheaders] "content-type"] - if { $content_type eq "" } { - set content_type [ns_guesstype [ad_conn file]] - } else { - ns_set idelkey [ns_conn outputheaders] "content-type" - } - ns_return 200 $content_type $parsed_template - } -} - --
XI. Future Improvements/Areas of Likely Change
- -XII. Authors
- --
-
- System creator -
- System owner: hqm@arsdigita.com -
- Documentation author: hqm@arsdigita.com
XII. Revision History
-The revision history table below is for this template - modify it as -needed for your actual design document.
-| Document Revision # | -Action Taken, Notes | -When? | -By Whom? |
|---|---|---|---|
| 0.1 | -Creation | -12/4/2000 | -Henry Minsky |
| 0.2 | -More specific template search algorithm, extended message catalog API to use package -keys or other namespace | -12/4/2000 | -Henry Minsky |
| 0.3 | -Details on how the <TRN> tag works in templates | -12/4/2000 | -Henry Minsky |
| 0.4 | -Definition of effective locale for template caching, documentation of TRN tag | -12/12/2000 | -Henry Minsky |
-
-hqm@arsdigita.com
- - - + + +
ACS 4 Globalization Detailed Design
by Henry Minsky ++ + +
I. Essentials
When applicable, each of the following items should +receive its own link: ++
-
+
- User directory: none +
- ACS administrator: acs-lang +
- Subsite administrator directory: none + +
- Tcl script directory: /api-doc +
- PL/SQL file: +
- Data model: + +
- Requirements document +
II. Introduction
+ ++ +
III. Historical Considerations
+ +V. Design Tradeoffs
+ +-
+
- Performance: availability and efficiency
+
+For Internationalization to be effective, it needs to be +integrated into every module in the system. Thus making the overhead +as low as possible is a priority, otherwise developers will be reluctant +to use it in their code. +
+Wherever possible, caching in AOLserver shared memory is used +to remove the need to touch the database. Precompiling of template +files should reduce the overhead to zero in most cases for translation +message lookups. The amount of overhead added to the request processor +can be reduced by caching filesystem information on matching of template +files for locales. + +
- Flexibility +
- Interoperability
+
+
- Reliability and robustness
+
+ +
- Usability
-
+
- Maintainability +
- Portability
+
+The ACS Tcl I18N APIs should be as close as possible to the ultimate Java +APIs. This means that using the same templates if possible, as well as the +same message catalogs and format strings should be a strong goal. + + +
- Reusability +
- Testability
+
+A set of unit tests are included in the acs-lang package, to +allow automatic testing after installation. + +
+ +
VI. API
+ +VI.A Locale API
+ +10.30 + +A Locale object represents a specific geographical, political, or +cultural region. An operation that requires a Locale to perform its +task is called locale-sensitive and uses the Locale to tailor +information for the user. For example, displaying a number is a +locale-sensitive operation--the number should be formatted according +to the customs/conventions of the user's native country, region, or +culture. + ++We will refer to a Locale by a combination of a language and country. +In the Java Locale API there is an optional variant which can be added to a locale, +which we will omit in the Tcl API. +
+
+The language is a valid ISO Language Code. These codes are the
+lower-case two-letter codes as defined by ISO-639. You can find a full
+list of these codes at a number of sites, such as:
+
+
+http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt
+
+The country is a valid ISO Country Code. These codes are the upper-case two-letter codes as defined by ISO-3166. You can find a full list of these codes at a number of sites, such as:
+
+http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html
+
+ +Examples are
+en_US English US ++ + +
+ ja_JP Japanese
+ fr_FR France French. +
+The i18n module figures out the locale for a current request +makes it accessible via the ad_locale function: +
+[ad_locale user locale] => fr_FR +[ad_locale subsite locale] => en_US ++ +It has not yet been decided how the user's preferred locale will be +initialized. For now, there is a site wide default package parameter +[parameter::get -parameter DefaultLocale -default "en_US"], and an API for setting +the locale with the preference stored in a session variable: + +The ad_locale_set function is used to set the user's preferred locale +to a desired value. It saves the value in the current session. + +
+ ad_locale_set locale "en_US" + will also automatically set [ad_locale user language] + ( to "en" in this case) + + ad_locale_set timezone "PST" + + ++ +The request processor should use the ad_locale API to figure out the +preferred locale for a request (perhaps combining user preference with +subsite defaults in some way). It will make this information accesible +via the ad_conn function: + +
+ ad_conn locale ++ + +
+ +
Character Sets and Encodings
+ +We refer to MIME character set names which are the valid values +which can be passed in a MIME header, such as ++Content-Type: text/html; charset=iso-8859-1 ++ +
You can obtain the preferred character set for a locale via the + ad_locale API shown below: + +
+ +
+set locale "en_US" +[ad_locale charset $locale] => "iso-8859-1" or "shift_jis" ++ Returns a case-insensitive name of a MIME character set. +
+ + +
+We already have an AOLserver function to convert a MIME charset name to a Tcl encoding name: +
+
+[ns_encodingforcharset "iso-8859-1"] => iso8859-1 ++ +
+ + +
Templating
+ +The goal of templates is to separate program logic from data +presentation. ++For presenting data in multiple languages, there are two basic ways to +use templates for a given abstract URL. Say we have the URL "foo", for example. +We can provide templates for it in the following ways: + +
-
+
- Separate template for each target language
+
Have a +copy of each template file in each language you support, e.g., +foo.en.adp, foo.fr.adp, foo.de.adp, etc. +
+We will refer to this style of template pages as language-specific templates. +
+
- A single template file for multiple languages
+
+You write your template to contain references to translation strings +either from data sources or using <TRN> tags. +
+ For example, a site might support multiple languages, but use a +single file foo.adp which contains no language-specific +content, and would only make use of data sources or <TRN> tags +which in turn use the message catalog to look up language-specific content. +
+We will refer to this style of page as a multilingual template. + +
+
+But for a page which has a very fixed format, such as a data entry +form, it would mean a lot less redundant work to use a single template +source page to handle all the languages, and to have all +language-dependent strings be looked in a message catalog. We can do this either by +creating data sources which call lang_message_lookup, or else +use the <TRN> tag to do the same thing from within an ADP file. + +
+ +
Caching multilingual ADP Templates
Message catalog lookups +can be potentially expensive, if many of them are done in a page. The +templating system can already precompile and and cache adp pages. +This works fine for a page in a specific language such as +foo.en.adp, but we need to modify the caching mechanism if we +want to use a single template file to target multiple languages. + +Computing the Effective Locale
+ ++Let's say you have a template file "foo.adp" and it contains calls to +look up message strings using the TRN tag: + +
++ +If the user requests the page foo, and their ad_locale +is "en_US" then effective locale is "en_US". Message lookups +are done using the effective locale. If the user's locale is "fr_FR", +then the effective locale will be "fr_FR". + ++<master> +<trn key=username_prompt>Please enter your username</tr> +<input type="text" name=username> +<p> +<trn key=password_prompt>Enter Password:</trn> +<input type=password name=passwd> ++
+ +If we evaluate the TRN tags at compile time then we need to associate +the effective locale in which the page was evaluated with the +cached compiled page code. +
+ +The effective locale of a template page that has an explicit locale, +such as a file named "foo.en.adp" or "foo.en_US.adp", will be that +explicit locale. So for example, even if a user has a preferred locale +of "fr_FR", if there is only a page named "foo.en.adp", then that page +will be evaluated (and cached) with an effective locale of en_US. + +
+ +
VI.B Naming of Template Files To Encode Language and Character Set
+ +10.40 +The templating system will use the Locale API to obtain the preferred +locale for a page request, and will attempt to find a template file which +most closely matches that locale. ++We will use the following convention for naming template files: +filename.locale_or_language.adp. + +
+Examples: +
+++foo.en_US.adp +foo.en.adp + +foo.fr_FR.adp +foo.fr.adp + +foo.ja_JP.adp +foo.ja.adp + ++
+ + +The user request has a locale which is of the form +language_country. If someone wants English, they will +implicitly be choosing a default, such as en_US or en_GB. The default +locale for a language can be configured in the system locale +tables. So for example the default locale for "en" could be "en_US". +
+ + + +The algorithm for finding the best matching template for a request in +a given locale is given below: + +
-
+
+
- Find the desired target locale using [ad_conn locale]
+ NOTE: This will always be a specific Locale (i.e., language_COUNTRY)
+
+
+
- Look for a template file whose locale suffix matches exactly.
+
+ For example, if the filename in the URL request is simply foo + and [ad_conn locale] returns en_US then look for a file + named foo.en_US.adp. + +
+
-
+If an exact match is not found, look for template files whose name
+ matches the language portion of the target locale.
+
+ + For example, if the URL request name is foo and [ad_conn locale] returns + en_US and a file named foo.en_US.adp is not found, then look for + all templates matching "en_*" as well as any template which just has the "en" suffix. + +
+ So for example if the user's locale en_GB and the following files exist: + +
+ foo.en_US.adp + +
+ then use foo.en_US.adp +
+ + If however both foo.en_US.adp and foo.en.adp +exist, then use foo.en.adp preferentially, i.e., don't +switch locales if you can avoid it. The reasoning here is that people +can be very touchy about switching locales, so if there is a generic +matching language template available for a language, use it rather +than using an incorrect locale-specific template. + + + +
+
-
+
+ If no locale-specific template is found, look for a template matching
+ just the language
+
+ + I.e., if the request is for en_US, and there exists a file + foo.en.adp, use that. + + +
+
- + +If no locale-specific template is found, look for a simple .adp file, + such as foo.adp. +
+Once a template file is found we must decide what character set it is +authored in, so that we can correctly load it into Tcl (which converts it +to UTF8 internally). +
+ +It would be simplest to mandate that all templates are authored in UTF8, but +that is just not a practical thing to enforce at this point, I believe. Many +designers and other people who actually author the HTML template files +will still find it easier to use legacy tools that author in their +"native" character sets, such as ShiftJIS in Japan, or BIG5 in China. +
+ +So we make the convention that the template file is authored in it's +effective locale's character set. For multilingual templates, +we will load the template in the site default character set as +specified by the AOLserver OutputCharset initializatoin +parameter. For now, we will say that authoring generic multilingual +adp files can and should be done in ASCII. Eventually we can switch to +using UTF8. + +
+A character set corresponding to a locale can be found using the +[ad_locale charset $locale] command. The templating +system should call this right after it computes the effective locale, so it +can set up that charset encoding conversion before reading the template file from disk. +
+ +We read the template file using this encoding, and set the default +output character set to it as well. Inside of either the .adp page or +the parent .tcl page, it is possible for the developer to issue a +command to override this default output character set. The way this +is done is currently to stick an explicit content-type header in +the AOLserver output headers, for example to force the output to ISO-8859-1, you +would do + + +
+ns_set put [ns_conn outputheaders] "content-type" "text/html; charset=iso-8859-1" ++ + +
+design questionWe should have an API for this. The hack now is that the +adp handler adp_parse_ad_locale user_file looks at the output headers, and if it sees a content type with +an explicit charset, it passes it along to ns_return. ++ + +
+The default character set for a template .adp file should +be the default system encoding. + +
+ +
VI.C Loading Regular Tcl Script Files
+ +10.50 By default, tcl and template files in the system will be +loaded using the default system encoding. This is generally ISO-8859-1 +for AOLserver running on Unix systems in English. ++This default can be +overridden by setting the AOLserver init parameter for the MIME type +of .tcl files to include an explcit character set. If an explicit +MIME type is not found, ns_encodingfortype will default to the +AOLserver init parameter value DefaultCharset if it is set. +
+ +Example AOLserver .ini configuration file to set default script file +and template file charset to ShiftJIS: + + +
+
+ns_section {ns/mimetypes }
+...
+ns_param .tcl {text/plain; charset=shift_jis}
+ns_param .adp {text/html; charset=shift_jis}
+
+ns_section ns/parameters
+...
+# charset hacking
+ns_param HackContentType 1
+ns_param URLCharset shift_jis
+ns_param OutputCharset shift_jis
+ns_param HttpOpenCharset shift_jis
+ns_param DefaultCharset shift_jis
+
+
+
+
+VI.A Message Catalog API
+ +We want to use something like the Java ResourceBundle, where the +developer can declare a set of resources for a given namespace +and locale. + ++For AOLserver/TCL, to make the message catalog more manageable, we will +split it into one message catalog per package, plus one default global +message namespace in case we need it. So for example, +
+Message lookups are done using a combination of a key string and a +locale or language, as well as an implicit package prefix on the key +string. The API for using the message catalog is as follows: +
+ +
++ + +The locale arg can actually be a full locale, or else a simple language abbrev, such as fr, en, etc. + +The lookup rules for finding strings based on key and locale are tried +in order as follows: ++lang_message_lookup locale key [default_string] ++ +lang_message_lookupis abbreviated by the procedure named "_", +which is the convention used by the GNU strings message catalog package. ++
-
+
+
- Lookup is first tried with the full locale (if present) and package.key + +
- Lookup is tried with just the language portion of the locale and + package.key + +
- Lookup is tried with the full locale and key without package prefix. + +
- Lookup is tried with language and key without package prefix. + +
+
+[lang_message_lookup $locale notes.title "Title"] + +can be abbreviated by +[_ $locale notes.title "Title"] + +# message key "title" is implicitly with respect to package key +# "notes", i.e., notes.title +[_ $locale title "Title"] + ++ +The string is looked up by the symbolic key notes.title (or title for short), and the constant value "Title" is supplied as documentation and +as a default value. Having a default value allows developers to code their application +immediately without waiting to populate the message catalog. +
+ +
Default Package Namespace
+ +By default, keys are prefixed with the name of the current package (if +a page request is being processed). So a lookup of the key "title" in +a page in the bboard package will actually reference the +"bboard.title" entry in the message catalog. + ++You can override this behavior by +either using a fully qualified key such as bboard.title or +else by changing the message catalog namespace using the +lang_set_package command: + +
+[lang_set_package "bboard"] ++ +So for example code that runs in a scheduled proc, where there is not necessarily +any concept of a "current package", would either use fully qualified keys to +look up messages, or else call lang_set_package before doing a message lookup. + + + +
+
Message Catalog Definition Files
+ +A message catalog is defined by placing a file in the catalog +subdirectory of a package. Each file defines a set of messages +in different locales, and the file is written in a character set +specified by it's file suffix: + ++/packages/bboard/catalog/ + bboard.iso-8859-1 + bboard.shift_jis + bboard.iso-8859-6 ++ + +A message catalog file consists of tcl code to define +messages in a given language or locale: + +
+ +_mr en mail_notification "This is an email notification" +_mr fr mail_notification "Le notification du email" +... + ++ + +In the example above, if the catalog file was loaded from the bboard +package, all of the keys would be prefixed autmatically with "
bboard.".
+
+Loading A Message Catalog At Package Init Time
+ +The API function ++lang_catalog_load package_key ++ +Is used to load the message catalogs for a package. +The catalog files are stored in a package subdirectory called catalog. Their +file names have the form *.encoding.cat, where encoding +is the name of a MIME charset encoding (not a Tcl charset name as was used +in a previous version of this command). + +
+/packages/bboard/catalog + /main.iso8859-1.cat + /main.shift_jis.cat + /main.iso-8859-6.cat + /other.iso8859-1.cat + /other.shift_jis.cat + /other.iso-8859-6.cat ++ + +
+ +You can add more pseudo-levels of hierarchy in naming the message keys, using +any separator character you want, for example + +
++which will be stored with the full key of bboard.alerts.mail_notification. + ++_mr fr alerts.mail_notification "Le notification du email" ++
+ +
Calling the Message Catalog API from inside of Templates
+ +Inside of a template, you can always make a call to the message +catalog API via a Tcl escape: + ++<%= [_ $locale bboard.passwordPrompt "Enter Password"]%> ++ +However, this is awkward and ugly to use. We have defined an ADP tag +which invokes the message catalog lookup. As explained in the previous +section, since our system precompiles adp templates, we can get a +performance improvement if we can cache the message lookups at +template compile time. +
+ +The <TRN> tag is a call to lang_message_lookup that can be used inside +of an ADP file. Here is the documention: + +
+ Procedure that gets called when the <trn> tag is encountered on an ADP page. + The purpose of the procedure is to register the text string enclosed within a + pair of <trn> tags as a message in the catalog, and to display the appropriate + translated string. + Takes three optional parameters:+ + + +lang,type+ andkey. ++
+ Example 1: Display the text string Hello on an ADP page (i.e. do nothing special): +keyspecifies the key in the message catalog. If it is omitted + this procedure returns simply the text enclosed by the tags. +langspecifies the language of the text string enclosed within the + flags. If it is ommitted value defaults to English. +typespecifies the context in which the translation is made. If omitted, + type is user which means that the translation is provided in the user's preferred language. +staticspecifies that this tag should be translated once at templat compile time, rather than dynamically every time the page is run. This will be unneccessaru and will be deprecated once we +have implemented effective locale based cacheing for templates. ++ <trn>Hello</trn> ++ Example 2: Assign the key key hello to the text string Hello and display + the translated string in the user's preferred language: ++ <trn key="hello">Hello</trn> ++ Example 3: Specify that Bonjour needs to be registered as the French translation + for the key hello (in addition to displaying the translation in the user's + preferred language): ++ <trn key="hello" lang="fr">Bonjour</trn> ++ Example 4: Register the string and display it in the preferred language of the + current user. Note that the possible values for thetype+ paramater are determined by what has been implemented in thead_localeprocedure. + By default, only theusertype is implemented. An example of a type that + could be implemented issubsite, + for displaying strings in the language of the subsite that owns the current web page. ++ <trn key="hello" type="user">Hello</trn> ++ ++ Example 5: Translates the string once at template compile time, using the effective local of the page. + +
+ <trn key="hello" static>Hello</trn> ++ + + +
VII. Data Model Discussion
+ +Internationalizing the Data Models
+ +Some data which is stored in ACS package and core database tables may +be presented to users, and thus may need to be stored in multiple +languages. Examples of this are the descriptions of package or site +parameters in the administrative interface, the "pretty names" of +objects, and group names. + ++ +Tables which are in acs kernel and have user-visible names that may +need to be translated in order to create an admin back end in another +language: + +
+user groups: + group_name + +acs_object_types: + pretty_name + pretty_plural + +acs_attributes: + pretty_name + pretty_plural + +acs_attribute_descriptions + description (clob) + +procedure add_description- add a lang arg ? + +acs_enum_values ? pretty_name + +acs_privileges: + pretty_name + pretty_plural + +apm_package_types + pretty_name + pretty_plural + + +apm_package "instance_name"? Maybe a given instance +gets instantiated with a name in the desired language? + + +apm_parameters: + parameter_name + section_name ++ +One approach is to split a table into two tables, one holding +language-independent datam, and the other holding language-dependent +data. This approach was described in the ASJ Multilingual Site Article. +
+In that case, it is convenient to create a new view which looks like +the original table, with the addition of a language column that you +can specify in the queries. +
+
Drawbacks to Splitting Tables
+ It is not totally transparent +to developers +Every query against the table which requests or +modifies language-dependent columns must now include a WHERE clause to +select the language. +
+Extra join may slow things down
The extra join of the two
+tables may cause queries to slow down, although I am not sure what the
+actual performance hit might be. It shouldn't be too large, because
+the join is against a fully indexed table.
+
+
+ + +
VIII. User Interface
+ +IX. Configuration/Parameters
+ +-
+
- +
- +
X. Code Examples
+-
+
- fconfigure -encoding blah +
- content type in outputheaders set for encoding conversion
+
+
+ad_proc adp_parse_ad_conn_file {} { + handle a request for an adp and/or tcl file in the template system. +} { + namespace eval template variable parse_level "" + #ns_log debug "adp_parse_ad_conn_file => file '[file root [ad_conn file]]'" + set parsed_template [template::adp_parse [file root [ad_conn file]] {}] + db_release_unused_handles + if { $parsed_template ne ""} { + set content_type [ns_set iget [ns_conn outputheaders] "content-type"] + if { $content_type eq "" } { + set content_type [ns_guesstype [ad_conn file]] + } else { + ns_set idelkey [ns_conn outputheaders] "content-type" + } + ns_return 200 $content_type $parsed_template + } +} + ++
XI. Future Improvements/Areas of Likely Change
+ +XII. Authors
+ +-
+
- System creator +
- System owner: hqm@arsdigita.com +
- Documentation author: hqm@arsdigita.com
XII. Revision History
+The revision history table below is for this template - modify it as +needed for your actual design document.
+| Document Revision # | +Action Taken, Notes | +When? | +By Whom? |
|---|---|---|---|
| 0.1 | +Creation | +12/4/2000 | +Henry Minsky |
| 0.2 | +More specific template search algorithm, extended message catalog API to use package +keys or other namespace | +12/4/2000 | +Henry Minsky |
| 0.3 | +Details on how the <TRN> tag works in templates | +12/4/2000 | +Henry Minsky |
| 0.4 | +Definition of effective locale for template caching, documentation of TRN tag | +12/12/2000 | +Henry Minsky |
+
+hqm@arsdigita.com
+ + + Index: openacs-4/packages/acs-lang/www/doc/i18n-requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-lang/www/doc/i18n-requirements.adp,v diff -u -r1.1.2.13 -r1.1.2.14 --- openacs-4/packages/acs-lang/www/doc/i18n-requirements.adp 11 Jun 2016 08:44:02 -0000 1.1.2.13 +++ openacs-4/packages/acs-lang/www/doc/i18n-requirements.adp 22 Jun 2016 07:45:44 -0000 1.1.2.14 @@ -319,8 +319,8 @@ to select an approprate locale-specific template file to use. The request locale is computed as per (see requirement 20.0).
Design note: this would probably be implemented by suffixing the locale or a locale abbreviation to the -template filename, such as foo.ja.adp or -foo.en_GB.adp.
+template filename, such as foo.ja.adp or +foo.en_GB.adp.
70.20A template file may be created for a partial locale (language only, without a territory), and the request processor should be able to find the closest match for the current request Index: openacs-4/packages/acs-lang/www/doc/i18n-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-lang/www/doc/i18n-requirements.html,v diff -u -r1.2 -r1.2.24.1 --- openacs-4/packages/acs-lang/www/doc/i18n-requirements.html 8 Aug 2003 12:21:28 -0000 1.2 +++ openacs-4/packages/acs-lang/www/doc/i18n-requirements.html 22 Jun 2016 07:45:44 -0000 1.2.24.1 @@ -20,18 +20,18 @@ applications which work properly in multiple locales with the lowest development and maintenance cost.
Definitions
-internationalization (i18n) +internationalization (i18n)The provision within a computer program of the capability of making itself adaptable to the requirements of different native languages, local customs and coded character sets.
-locale
+locale
The definition of the subset of a user's environment that depends on language and cultural conventions.
-localization (L10n)
+localization (L10n)
The process of establishing information within a computer system specific to the operation of particular native languages, local customs and coded character sets.
-globalization
+globalization
A product development approach which ensures that software products are usable in the worldwide markets through a combination of internationalization and localization.
@@ -138,16 +138,16 @@ ... ? Anyone know how they deal with i18n ?V. Related Links
-
- System/Package "coversheet" - where all documentation for -this software is linked off of
-- Design document
-- Developer's guide
-- User's guide
-- Other-cool-system-related-to-this-one document
+- System/Package "coversheet" - where all documentation for +this software is linked off of
+- Design document
+- Developer's guide
+- User's guide
+- Other-cool-system-related-to-this-one document
-
LI18NUX 2000 Globalization Specification: http://www.li18nux.net/ -Mozilla +
Mozilla i18N Guidelines: http://www.mozilla.org/docs/refList/i18n/l12yGuidelines.html
- Test plan
-- Competitive system(s)
+- Test plan
+- Competitive system(s)
VI Requirements
Because the requirements for globalization affect many areas of the system, we will break up the requirements into phases, with a base required set of features, and then stages of increasing functionality.VI.A Locales
-10.0 A standard representation of locale will be used +10.0 A standard representation of locale will be used throughout the system. A locale refers to a language and territory, and is uniquely identified by a combination of ISO language and ISO country abbreviations. -See +See Content Repository Requirement 100.20 -10.10 Provide a consistent representation and API for +
10.10 Provide a consistent representation and API for creating and referencing a locale
-10.20 There will be a Tcl library of locale-aware +
10.20 There will be a Tcl library of locale-aware formatting and parsing functions for numbers, dates and times. -Note that Java has builtin support for these already.
-10.30 For each locale there will be default date, number +Note that Java has builtin support for these already.
+10.30 For each locale there will be default date, number and currency formats.
VI.B Associating a Locale with a Request
-20.0 The request processor must have a mechanism for +20.0 The request processor must have a mechanism for associating a locale with each request. This locale is then used to select the appropriate template for a request, and will also be passed as the locale argument to the message catalog or locale-specific formatting functions.-20.10 The locale for a request should be computed by the +
20.10 The locale for a request should be computed by the following method, in descending order of priority:
- get locale associated with subsite or package id
- get locale from user preference
- get locale from site wide default -
20.20 An API will be provided for getting the current +
20.20 An API will be provided for getting the current request locale from the
ad_connstructure.VI.C Resource Bundles / Content Repository
-30.0 A mechanism must be provided for a developer to group a +30.0 A mechanism must be provided for a developer to group a set of arbitrary content resources together, keyed by a unique identifier and a locale.For example, what approaches could be used to implement a @@ -219,48 +219,48 @@ convention assigning a common prefix to key strings in the message catalog.
VI.D Message Catalog for String Translation
-40.0 A message catalog facility will provide a database of +40.0 A message catalog facility will provide a database of translations for constant strings for multilingual applications. It must support the following:-40.10 Each message will referenced via unique a key.
-40.20 The key for a message will have some hierarchical +
40.10 Each message will referenced via unique a key.
+40.20 The key for a message will have some hierarchical structure to it, so that sets of messages can be grouped with respect to a module name or package path.
-40.30 The API for lookup of a message will take a locale +
40.30 The API for lookup of a message will take a locale and message key as arguments, and return the appropriate translation of that message for the specifed locale.
-40.40 The API for lookup of a message will accept an +
40.40 The API for lookup of a message will accept an optional default string which can be used if the message key is not found in the catalog. This lets the developer get code working and tested in a single language before having to initialize or update a message catalog.
-40.50 For use within templates, custom tags which invoke +
40.50 For use within templates, custom tags which invoke the message lookup API will be provided.
-40.60 Provide a method for importing and exporting a flat +
40.60 Provide a method for importing and exporting a flat file of translation strings, in order to make it as easy as possible to create and modify message translations in bulk without having to use a web interface.
-40.70 Since translations may be in different character +
40.70 Since translations may be in different character sets, there must be provision for writing and reading catalog files in different character sets. A mechanism must exist for identifying the character set of a catalog file before reading it.
-40.80 There should be a mechanism for tracking +
40.80 There should be a mechanism for tracking dependencies in the message catalog, so that if a string is modified, the other translations of that string can be flagged as needing update.
-40.90 The message lookup must be as efficient as possible +
40.90 The message lookup must be as efficient as possible so as not to slow down the delivery of pages.
+version control almost for free?
-Design question: Is there any reason to +Design question: Is there any reason to implement the message catalog on top of the content repository as the underlying storage and retrieval service, with a layer of caching for performance? Would we get a nice user interface and -version control almost for free?VI.E Character Set Encoding
-Character Sets -50.0 A locale will have a primary associated character +Character Sets +
50.0 A locale will have a primary associated character set which is used to encode text in the language. When given a locale, we can query the system for the associated character set to use.
@@ -281,134 +281,134 @@Writing data to the filesystem -
-Design question: Do we want to mandate +Design question: Do we want to mandate that all template files be stored in UTF8? I don't think so, because most people don't have Unicode editors, or don't want to be bothered with an extra step to convert files to UTF8 and back when -editing them in their favorite editor.Same question for script and template +editing them in their favorite editor.
+Same question for script and template files, how do we know what language and character set they are authored in? Should we overload the filename suffix (e.g., -'.shiftjis.adp', '.ja_JP.euc.adp')?
-The simplest design is probably just to +'.shiftjis.adp', '.ja_JP.euc.adp')?
+The simplest design is probably just to assign a default mapping from each locale to character a set: e.g. ja_JP -> ShiftJIS, fr_FR -> ISO-8859-1. +++ (see new ACS/Java -notes) +++
+notes) +++Tcl Source File Character Set
There are two classes of Tcl files loaded by the system; library files loaded at server startup, and page script files, which are run on each page request.-
-Should we require all Tcl files be stored +Should we require all Tcl files be stored as UTF8? That seems too much of a burden on -developers.50.10 Tcl library files can be authored in any character +developers.
+50.10 Tcl library files can be authored in any character set. The system must have a way to determine the character set before loading the files, probably from the filename.
-50.20 Tcl page script files can be authored in any +
50.20 Tcl page script files can be authored in any character set. The system must have a way to determine the character set before loading the files, probably from the filename.
Submitted Form Data Character Set
-50.30 Data which is submitted with a HTTP request using a +50.30 Data which is submitted with a HTTP request using a GET or POST method may be in any character set. The system must be able to determine the encoding of the form data and convert it to Unicode on demand. -50.35 The developer must be able to override the default +
50.35 The developer must be able to override the default system choice of character set when parsing and validating user form data.
-50.30.10 Extra hair: In Japan and some other Asian +
50.30.10 Extra hair: In Japan and some other Asian languages where there are multiple character set encodings in common use, the server may need to attempt to do an auto-detection of the character set, because buggy browsers may submit form data in an unexpected alternate encoding.
Output Character Set
-50.40 The output character set for a page request will be +50.40 The output character set for a page request will be determined by default by the locale associated with the request (see requirement 20.0). -50.50 It must be possible for a developer to manually +
50.50 It must be possible for a developer to manually override the output character set encoding for a request using an API function.
VI.F ACS Kernel Issues
-60.10 All ACS error messages must use the +60.10 All ACS error messages must use the message catalog and the request locale to generate error message for the appropriate locale. -60.20 Web server error messages such as 404, 500, etc +
60.20 Web server error messages such as 404, 500, etc must also be delivered in the appropriate locale.
-60.30 Where files are written or read from disk, their +
60.30 Where files are written or read from disk, their filenames must use a character set and character values which are safe for the underlying operating system.
VI.G Templates
-70.0 For a given abstract URL, the designer may +70.0 For a given abstract URL, the designer may create multiple locale-specific template files may be created (one per locale or language) -70.10 For a given page request, the system must be able +
70.10 For a given page request, the system must be able to select an approprate locale-specific template file to use. The request locale is computed as per (see requirement 20.0).
-Design note: this would probably be +
+Design note: this would probably be implemented by suffixing the locale or a locale abbreviation to the -template filename, such as foo.ja.adp or -foo.en_GB.adp.
-70.20A template file may be created for a partial locale +template filename, such as foo.ja.adp or +foo.en_GB.adp.
70.20A template file may be created for a partial locale (language only, without a territory), and the request processor should be able to find the closest match for the current request locale.
-70.30 A template file may be created in any character +
70.30 A template file may be created in any character set. The system must have a way to know which character set a template file contains, so it can properly process it.
Formatting Datasource Output in Templates
-70.50 The properties of a datasource column may include a +70.50 The properties of a datasource column may include a datatype so that the templating system can format the output for the current locale. The datatype is defined by a standard ACS datatype plus a format token or format string, for example: a date column might be specified as 'current_date:date LONG,' or 'current_date:date "YYYY-Mon-DD"'Forms
-70.60 The forms API must support construction of +70.60 The forms API must support construction of locale-specific HTML form widgets, such as date entry widgets, and form validation of user input data for locale-specific data, such as dates or numbers. -70.70 For forms which allow users to upload files, a +
70.70 For forms which allow users to upload files, a standard method for a user to indicate the charset of a text file being uploaded must be provided.
-Design note: this presumably applies to -uploading data to the content repository as well
+Design note: this presumably applies to +uploading data to the content repository as well
VI.H Sorting and Searching
-80.10 Support API for correct collation (sorting +80.10 Support API for correct collation (sorting order) on lists of strings in locale-dependent way. -80.20 For the Tcl API, we will say that locale-dependent +
80.20 For the Tcl API, we will say that locale-dependent sorting will use Oracle SQL operations (i.e., we won't provide a Tcl API for this). We require a Tcl API function to return the correct incantation of NLS_SORT to use for a given locale with
-ORDER BYclauses in queries.80.40 The system must handle full-text search in any +
80.40 The system must handle full-text search in any supported language.
VI.G Time Zones
-90.10 Provide API support for specifying a time +90.10 Provide API support for specifying a time zone -90.20 Provide an API for computing time and date +
90.20 Provide an API for computing time and date operations which are aware of timezones. So for example a calendar module can properly synchronize items inserted into a calendar from users in different time zones using their own local times.
-90.30 Store all dates and times in universal time zone, +
90.30 Store all dates and times in universal time zone, UTC.
-90.40 For a registered users, a time zone preference +
90.40 For a registered users, a time zone preference should be stored.
-90.50 For a non-registered user a time zone preference +
90.50 For a non-registered user a time zone preference should be attached via a session or else UTC should be used to display every date and time.
-90.60 The default if we can't determine a time zone is to +
90.60 The default if we can't determine a time zone is to display all dates and times in some universal time zone such as GMT.
VI.H Database
-100.10 Since UTF8 strings can use up to three (UCS2) or +
100.10 Since UTF8 strings can use up to three (UCS2) or six (UCS4) bytes per character, make sure that column size declarations in the schema are large enough to accomodate required data (such as email addresses in Japanese).
@@ -418,9 +418,9 @@ in web page over an HTTP connection, it is necessary to be able to specify what character set encoding to use.-@@ -459,8 +459,8 @@110.10 The email message sending API will allow for a +
110.10 The email message sending API will allow for a character set encoding to be specified.
-110.20 The email accepting API will allow for character +
110.20 The email accepting API will allow for character set to be parsed correctly (hopefully a well formatted message will have a MIME character set content type header)
-hqm@arsdigita.com +hqm@arsdigita.com
Last modified: $Date$
Index: openacs-4/packages/calendar/www/cal-item-create-recurrence.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/calendar/www/cal-item-create-recurrence.adp,v diff -u -r1.14 -r1.14.2.1 --- openacs-4/packages/calendar/www/cal-item-create-recurrence.adp 27 Oct 2014 16:41:07 -0000 1.14 +++ openacs-4/packages/calendar/www/cal-item-create-recurrence.adp 22 Jun 2016 07:43:59 -0000 1.14.2.1 @@ -13,9 +13,9 @@ #calendar.lt_You_are_choosing_to_m#
-#calendar.Date# @cal_item.start_date@
-#calendar.Time# @cal_item.start_time@ - @cal_item.end_time@
-#calendar.Details# @cal_item.description@
+#calendar.Date# @cal_item.start_date@
+#calendar.Time# @cal_item.start_time@ - @cal_item.end_time@
+#calendar.Details# @cal_item.description@
-
<%
foreach attachment $item_attachments {
- template::adp_puts "
![](\"/resources/acs-subsite/attach.png\")
[lindex $attachment 1] \[#attachments.remove#\] "
+ template::adp_puts "- [lindex $attachment 1] \[#attachments.remove#\] "
}
%>
III. System/Application Overview
In our system, a -party-specific event is an event associated with a particular +party-specific event is an event associated with a particular party, typically of the sort scheduled by that party or of particular interest to members of that party. For example, a reading group may wish to associate an upcoming book signing event with their reading group party using the Calendar application. -A user's calendar is the aggregate of the party-specific +
A user's calendar is the aggregate of the party-specific events which are associated with parties of which the user is a member and which have been specified by this user as desirable for calendar inclusion. Users will have the option to suppress the inclusion of all @@ -70,18 +70,18 @@
Calendar Views covers those aspects of the application which +adding a temporal aspect to activities . +
Calendar Views covers those aspects of the application which pertain to the display of calendar events for a particular span of time. -
Navigation covers those aspects of the application which pertain +
Navigation covers those aspects of the application which pertain to ways in which the end-user can change the timespan currently being displayed.
IV. Use-cases and User-scenarios
@@ -96,7 +96,7 @@Groups and Parties can have a collective calendar that stands +
Groups and Parties can have a collective calendar that stands apart from the private individual calendar. This would be useful to display calendar events for the public, for whom there is no individual calendar. For example, ArsDigita can display a schedule of upcoming bootcamps, lectures @@ -116,7 +116,7 @@ need to support all the event managment and calendar views had by individual calendars, and in addition, the role of calendar administrator must be assigned to handle event managment. -
Administrators for a group and party wide calendar are given +
Administrators for a group and party wide calendar are given create, read, and write permissions on each individual item on the calendar. He or she also has the privilege to change the permissions for each of these items and also individual's ability to interact with these items. @@ -155,283 +155,283 @@
VI.A Requirements: Private Calendar
-10 Private Calendar -10.0 User Interface -
10.0.10 The calendar page should indicate whether or not private, +10 Private Calendar +
10.0 User Interface +
10.0.10 The calendar page should indicate whether or not private, public or party-specific events are to be displayed. -
10.0.20 The calendar should support navigation to view different +
10.0.20 The calendar should support navigation to view different dates in a simple manner. -
10.0.30 Links to different calendar functions should be clear +
10.0.30 Links to different calendar functions should be clear and obvious. -
10.0.40 Each calendar item should be displayed with its subject +
10.0.40 Each calendar item should be displayed with its subject and time span as the basic information. -
10.10 Views -
10.10.0 Different views should be easily selectable. -
10.10.0 Different views should also be indicated in a clear and +
10.10 Views +
10.10.0 Different views should be easily selectable. +
10.10.0 Different views should also be indicated in a clear and noticeable location -
10.10.10 List View -
10.10.10.10 The calendar should support a view showing selected +
10.10.10 List View +
10.10.10.10 The calendar should support a view showing selected items in a tabular list format. -
10.10.10.20 Columns should include date, time, and other relevant +
10.10.10.20 Columns should include date, time, and other relevant information. -
10.10.10.30 The columns should be sortable. -
10.10.10.40 There should be at least two lists of items. One +
10.10.10.30 The columns should be sortable. +
10.10.10.40 There should be at least two lists of items. One list should consist of items whose dates occur within a user-specified number of days of the currently viewed date. One list should consist of items that have been added within a user-specified number of days of the current date. -
10.10.20 Day View -
10.10.20.10 The calendar should support a view showing all the +
10.10.20 Day View +
10.10.20.10 The calendar should support a view showing all the events for a particular day. -
10.10.20.20 This view should show the events arranged chronologically +
10.10.20.20 This view should show the events arranged chronologically with a time guide along one side. -
10.10.20.30 The range of the time guide should be user-specifiable. -
10.10.20.40 The user should have the option of compressing the +
10.10.20.30 The range of the time guide should be user-specifiable. +
10.10.20.40 The user should have the option of compressing the time guide so that only those time intervals upon which fall selected calendar events are shown. -
10.10.20.50 Overlapping events should be displayed in an easy +
10.10.20.50 Overlapping events should be displayed in an easy to understand fashion. -
10.10.20.60 There should be a simple mechanism for adding events +
10.10.20.60 There should be a simple mechanism for adding events which start at a particular hour. -
10.10.20.70 The day view should support events that don't have +
10.10.20.70 The day view should support events that don't have a specified start and end time, and the time guide should include a slot for these items. -
10.10.30 Week View -
10.10.30.10 The calendar should support a view showing all the +
10.10.30 Week View +
10.10.30.10 The calendar should support a view showing all the events for a particular week. -
10.10.30.20 The events for a particular day should be grouped +
10.10.30.20 The events for a particular day should be grouped together. -
10.10.30.30 There should be a simple mechanism for adding an +
10.10.30.30 There should be a simple mechanism for adding an event for a particular day. -
10.10.30.40 The currently selected day should be highlighted +
10.10.30.40 The currently selected day should be highlighted or otherwise clearly indicated to the user. -
10.10.30.50 There should some way to move to the next and previous +
10.10.30.50 There should some way to move to the next and previous week from this particular view. -
10.10.40 Month View -
10.10.40.10 The calendar should support a view showing all the +
10.10.40 Month View +
10.10.40.10 The calendar should support a view showing all the items for a particular month. -
10.10.40.20 The events for a particular day should be grouped +
10.10.40.20 The events for a particular day should be grouped together. -
10.10.40.30 There should be a simple mechanism for adding an +
10.10.40.30 There should be a simple mechanism for adding an event for a particular day. -
10.10.40.40 The currently selected day should be indicated. -
10.10.40.50 The application should display only some of the events +
10.10.40.40 The currently selected day should be indicated. +
10.10.40.50 The application should display only some of the events per day on the month calendar as oppose to every item. -
10.10.40.60 There should some way to move to the next and previous +
10.10.40.60 There should some way to move to the next and previous week from this particular view. -
10.10.40.70 For each day, there should be a link to the day view +
10.10.40.70 For each day, there should be a link to the day view for that day. -
10.10.50 Year View -
10.10.50.10 As a navigational mechanism, the calendar should +
10.10.50 Year View +
10.10.50.10 As a navigational mechanism, the calendar should support a view that shows all months and days in a particular year but not necessarily with any information on items for the days displayed. -
10.10.50.20 For each month, there should be a link to the month +
10.10.50.20 For each month, there should be a link to the month view of that month. -
10.10.50.30 For each day, there should be a link to the day view +
10.10.50.30 For each day, there should be a link to the day view of that day. -
10.20 Navigation -
10.20.10 Navigation Widget -
10.20.10.10 The calendar should provide a widget for collecting +
10.20 Navigation +
10.20.10 Navigation Widget +
10.20.10.10 The calendar should provide a widget for collecting together related navigation links. This should be similar to the widget provided by Yahoo Calendar and Excite Planner. -
10.20.10.20 Navigation to a different date should maintain the +
10.20.10.20 Navigation to a different date should maintain the same view. -
10.20.10.30 In the list, day, and week views, the widget should +
10.20.10.30 In the list, day, and week views, the widget should display a mini calendar of the days of the current month. Each day should be a link except for the currently viewed day which should not be a link and should be highlighted in some manner. -
10.20.10.40 In the month view, the widget should contain a list +
10.20.10.40 In the month view, the widget should contain a list of the months of the year. Each month should be a link except for the month containing the currently viewed day which should not be a link and should be highlighted in some manner. -
10.20.10.50 In the year view, the widget should contain a short +
10.20.10.50 In the year view, the widget should contain a short list of years before and after the current year. Each year should be a link except for the year containing the currently viewed day which should not be a link and should be highlighted in some manner. -
10.20.10.60 The widget should contain some mechanism for entering +
10.20.10.60 The widget should contain some mechanism for entering an arbitrary date using a clearly defined format, such as that employed by Yahoo Calendar. -
10.20.10.70 The widget should clearly display today's date along +
10.20.10.70 The widget should clearly display today's date along with some mechanism for navigating to that date. -
10.20.10.80 In the list, day, and week views there should be +
10.20.10.80 In the list, day, and week views there should be a mechanism for jumping forwards or backwards by a whole month at a time. -
10.20.10.90 In the month and year views, there should be a mechanism +
10.20.10.90 In the month and year views, there should be a mechanism for jumping forwards or backwards by a year at a time. -
10.20.20 View Specific Navigation -
10.20.20.10 Each view except for 'list' should have some easy +
10.20.20 View Specific Navigation +
10.20.20.10 Each view except for 'list' should have some easy mechanism for jumping forward or backward by the interval being viewed. -
10.20.20.20 Selecting a day in week, month, or year view should +
10.20.20.20 Selecting a day in week, month, or year view should take you to the day view for the that day. -
10.20.20.30 Selecting a month in year view should take you to +
10.20.20.30 Selecting a month in year view should take you to the month view for that month. -
10.30 Adding Events -
10.30.10 Adding an event should involve entering information +
10.30 Adding Events +
10.30.10 Adding an event should involve entering information for the event in a form and then submitting that form. Form should include title, start date and time, or an explicit indication that the event does not have a start time. Default values should already be entered with the correct time zone offset in place. Non-required fields should include end time or duration, type information, a description, to which party the event belongs, and an indicator as to whether or not this event recurs. -
10.30.20 There should be a simple, clearly labeled link for adding +
10.30.20 There should be a simple, clearly labeled link for adding an event. The date should default to the currently viewed date and the present time. -
10.30.30 The time guide in the day view should have links from +
10.30.30 The time guide in the day view should have links from each hour and from the slot for items with no start time. -
10.30.40 Selecting the 'no start time' link should bring up the +
10.30.40 Selecting the 'no start time' link should bring up the form with the date defaulting to the currently viewed date and the 'no start time' indicator set. -
10.30.50 Selecting a link from a specific hour should bring up +
10.30.50 Selecting a link from a specific hour should bring up the form with the date defaulting to the currently viewed date, the start time to the hour selected, and the end time to one hour later. -
10.30.60 The week view should have a link for each day for adding +
10.30.60 The week view should have a link for each day for adding an item. -
10.30.70 The month view should have a link for each day for adding +
10.30.70 The month view should have a link for each day for adding an item. -
10.30.80 As in the Yahoo style calendar, there should be a 'quick +
10.30.80 As in the Yahoo style calendar, there should be a 'quick add' box on the side of their calendar that allows user to add events quickly without having to click through on different days and different views. -
10.40 Viewing Events -
10.40.10 Selecting an event's title from any view should display +
10.40 Viewing Events +
10.40.10 Selecting an event's title from any view should display details for that event, including links to edit, add attachment, and delete. -
10.50 Editing Events -
10.50.10 While viewing an event, select 'Edit'. You should get +
10.50 Editing Events +
10.50.10 While viewing an event, select 'Edit'. You should get a form allowing you to edit the title, date, times, types, and description for the event. Non-recurring items should have a "Repeat?" field but not -an "Update?" field. [need to clarify what this means] -
10.60 Adding Recurring Events -
10.60.10 If the recurring events indicator is selected in the +an "Update?" field. [need to clarify what this means] +
10.60 Adding Recurring Events +
10.60.10 If the recurring events indicator is selected in the form for adding an item, then after submitting that form, a second form should be presented which summarizes the date and time of the item and provides fields to set how the item recurs. -
10.60.20 The form should include fields to enter the type of +
10.60.20 The form should include fields to enter the type of interval, the number of intervals between recurrences, and any specific information for the selected type of interval. -
10.70 Editing Recurring Events -
10.70.10 Selecting Edit when viewing a repeating item should +
10.70 Editing Recurring Events +
10.70.10 Selecting Edit when viewing a repeating item should add a field at the bottom of the form to specify whether any changes should be applied to only the current instance being edited or to all instances of this recurring item. -
10.80 Adding Attachments to Events -
10.80.10 When viewing an item, there should be a link to add +
10.80 Adding Attachments to Events +
10.80.10 When viewing an item, there should be a link to add an attachment to that item. Selecting that link should bring up a form to add attachments of various types. -
10.80.20 The form should include a field for the title of the +
10.80.20 The form should include a field for the title of the attachment. -
10.80.30 One type of admissible attachment supported should be +
10.80.30 One type of admissible attachment supported should be an uploaded file. This type should be handled in the standard ACS manner. -
10.80.40 One type of admissible attachment should be a URL. -
10.80.50 One type of admissible attachment should be a block +
10.80.40 One type of admissible attachment should be a URL. +
10.80.50 One type of admissible attachment should be a block of text. The form should provide a text box for entering the text and a way to indicate if the text is plaintext or HTML. -
10.80.60 After adding an attachment of any sort, the calendar +
10.80.60 After adding an attachment of any sort, the calendar should return to the view of the item which should have a list of attachments including the attachment just added. -
10.80.70 For each attachment listed, there should be displayed +
10.80.70 For each attachment listed, there should be displayed -- when permissions admit -- the title of the attachment, a link to the content of the attachment, a link to manage the attachment, and a link to edit it. -
10.80.80 For a file attachment, the content link should return +
10.80.80 For a file attachment, the content link should return the content of the file. -
10.80.90 For a URL attachment, the content link should navigate +
10.80.90 For a URL attachment, the content link should navigate to the URL. -
10.80.100 For a text attachment, the content link should display +
10.80.100 For a text attachment, the content link should display the entered text. -
10.80.110 The manage link links to the management page of the -corresponding file in the file-storage system. [file-storage or -CR?] -
10.80.120 The edit link allows direct editing of the content +
10.80.110 The manage link links to the management page of the +corresponding file in the file-storage system. [file-storage or +CR?] +
10.80.120 The edit link allows direct editing of the content of the attachment. -
10.90 Inviting other groups to view Events -
10.90.10 The application should have a link that lets the owner +
10.90 Inviting other groups to view Events +
10.90.10 The application should have a link that lets the owner of the event to invite other groups, individual or parties to add this event to their personal calendars. -
10.100 Deleting events -
10.100.10 When viewing an item, there should be a link to delete +
10.100 Deleting events +
10.100.10 When viewing an item, there should be a link to delete that item. -
10.100.20 Selecting the delete link should bring up a confirmation +
10.100.20 Selecting the delete link should bring up a confirmation dialog. -
10.100.30 If the item is not recurring, then the choice button +
10.100.30 If the item is not recurring, then the choice button will simply be labeled 'OK'. -
10.100.40 If the item is recurring, then in addition to the choice +
10.100.40 If the item is recurring, then in addition to the choice buttons, there should be a selection to indicate either the current instance only or all occurrences. -
10.100.50 Selecting 'Cancel' should return to the item view. -
10.100.60 Selecting 'OK' should delete the item in question. -
10.100.70 If the item was recurring and 'all occurrences' had +
10.100.50 Selecting 'Cancel' should return to the item view. +
10.100.60 Selecting 'OK' should delete the item in question. +
10.100.70 If the item was recurring and 'all occurrences' had been selected, then all other occurrences of the item should be deleted as well. -
10.100.80 Selecting OK should return to the view where the item +
10.100.80 Selecting OK should return to the view where the item was originally selected.
VI.B Requirements: Party-Specific Events
-20 Party-Specific Events -20.10 The calendar should display a list of calendars to which +20 Party-Specific Events +
20.10 The calendar should display a list of calendars to which the user has access. At a minimum, this will include the user's personal calendar and a public events calendar. If the user belongs to parties that have party-specific events associated with them, there should be additional links to these party-specific events as well as the calendar of the party to which the user belongs. -
20.30 On the personal calendar, there should also be a toggle +
20.30 On the personal calendar, there should also be a toggle for each such party that controls whether or not events from that party appear on the personal calendar. -
20.40 On a user's calendar, party-specific events should indicate +
20.40 On a user's calendar, party-specific events should indicate to which party they are specific. -
20.50 The link for adding an event should clearly indicate whether +
20.50 The link for adding an event should clearly indicate whether a party-specific item or a personal item will be created.
VI.C Requirements: Managing Party-Specific Events
-30 Managing Party-Specific Events -30.10 If the user has write permission to any parties, when he +30 Managing Party-Specific Events +
30.10 If the user has write permission to any parties, when he chooses to add an event, the choice of which party to associate with that event is given. -
30.20 There should also be a page where permissions of read, +
30.20 There should also be a page where permissions of read, write, approve, and delete can be given to different parties -
30.30 There should be a link to the admin page for the group. -
30.40 There should be a way to delete the calendar. This +
30.30 There should be a link to the admin page for the group. +
30.40 There should be a way to delete the calendar. This route should involve passing the user through a confirmation dialog.
VI.D Requirements: Calendar Administration
-40 Calendar Administration -40.10 Calendar User Privilege Administration -
40.10.10 Cal Admin must have access to pages where permissions +40 Calendar Administration +
40.10 Calendar User Privilege Administration +
40.10.10 Cal Admin must have access to pages where permissions can be set for different parties -
40.10.20 Cal Admin can also add new user party/groups/person +
40.10.20 Cal Admin can also add new user party/groups/person to the entire calendar -
40.10.30 Cal Admin can also add new user party/groups/person +
40.10.30 Cal Admin can also add new user party/groups/person to indivdual calendar items -
40.20 Calendar Items Administration -
40.20.10 Provides the funcationality to delete, add, edit any +
40.20 Calendar Items Administration +
40.20.10 Provides the funcationality to delete, add, edit any item on the calendar -
40.20.20 Provides the funcatinality to allow Calendar Administrator +
40.20.20 Provides the funcatinality to allow Calendar Administrator to change the permissions on each calendar item. -
40.20.20 Provides the funcatinality to allow Calendar Administrator +
40.20.20 Provides the funcatinality to allow Calendar Administrator
to change the default permissions of the entire calendar
VI.E Requirements: API
-50 API -50.10 Calendar Events Manipulation -
50.10.10 Provide a function to add a new item to a calendar. +50 API +
50.10 Calendar Events Manipulation +
50.10.10 Provide a function to add a new item to a calendar. This function should support specifying all the values that can be specified in the 'add item' form. It should allow creating either a user or a party-specific item. Iit should support specifying a mapping between the new item and an arbitrary object in the database. -
50.20 Calendar Views -
50.20.10 Provide a function to generate the HTML for the list +
50.20 Calendar Views +
50.20.10 Provide a function to generate the HTML for the list view. -
50.20.20 Provide a function to generate the HTML for the day +
50.20.20 Provide a function to generate the HTML for the day view. -
50.20.30 Provide a function to generate the HTML for the week +
50.20.30 Provide a function to generate the HTML for the week view. -
50.20.40 Provide a function to generate the HTML for the month +
50.20.40 Provide a function to generate the HTML for the month view. -
50.20.50 Provide a function to generate the HTML for the year +
50.20.50 Provide a function to generate the HTML for the year view. -
50.20.60 Provide a function to generate the HTML for the calendar +
50.20.60 Provide a function to generate the HTML for the calendar navigation. -
50.20.70 Provide a function to generate the HTML for the complete +
50.20.70 Provide a function to generate the HTML for the complete calendar.
VII. Revision History
Index: openacs-4/packages/acs-templating/resources/forms/blue.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/resources/forms/blue.adp,v diff -u -r1.4 -r1.4.2.1 --- openacs-4/packages/acs-templating/resources/forms/blue.adp 16 Jun 2015 08:57:09 -0000 1.4 +++ openacs-4/packages/acs-templating/resources/forms/blue.adp 22 Jun 2016 07:48:43 -0000 1.4.2.1 @@ -13,7 +13,7 @@@@ -57,7 +57,7 @@
- \@formerror.@elements.id@;noquote\@ + \@formerror.@elements.id@;noquote\@
\@formerror.@elements.id@;noquote\@ + color="red">\@formerror.@elements.id@;noquote\@
| @form_properties.title@ | +@form_properties.title@ | |
| No items | ||
| No items | ||
\@formerror.@elements.id@\@
\@formerror.@elements.id@\@
- \@formerror.@elements.id@\@
+ \@formerror.@elements.id@\@
- \@formerror.@elements.id@;noquote\@ + \@formerror.@elements.id@;noquote\@
@@ -51,7 +51,7 @@
- \@formerror.@elements.id@;noquote\@ + \@formerror.@elements.id@;noquote\@
\@formerror.@elements.id@;noquote\@ + color="red">\@formerror.@elements.id@;noquote\@
- \@formerror.@elements.id@;noquote\@ + \@formerror.@elements.id@;noquote\@
@@ -62,7 +62,7 @@
- \@formerror.@elements.id@;noquote\@ + \@formerror.@elements.id@;noquote\@
- \@formerror.@elements.id@;noquote\@
+ \@formerror.@elements.id@;noquote\@
\@formerror.@elements.id@;noquote\@ + color="red">\@formerror.@elements.id@;noquote\@
Data sources for @code_stub@.acs
| Type: | @datasources.structure@ | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Comments: | @datasources.comment@ | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| @datasources.input_name@ | @datasources.input_type@; @datasources.input_comment@ | |
|---|---|---|
| @datasources.input_name@ | @datasources.input_type@; @datasources.input_comment@ | |
Index of acs-templating/admin
- test+ test
Christian Brechbühler Index: openacs-4/packages/acs-templating/www/admin/test/index.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/admin/test/index.html,v diff -u -r1.1.1.1 -r1.1.1.1.30.1 --- openacs-4/packages/acs-templating/www/admin/test/index.html 13 Mar 2001 22:59:27 -0000 1.1.1.1 +++ openacs-4/packages/acs-templating/www/admin/test/index.html 22 Jun 2016 07:48:43 -0000 1.1.1.1.30.1 @@ -7,11 +7,11 @@
Index of acs-templating/admin/test
- include-0- if
- chain_frac-0
- chain_frac-1
- chain_frac-2
+ include-0
+ if
+ chain_frac-0
+ chain_frac-1
+ chain_frac-2
Christian Brechbuehler Index: openacs-4/packages/acs-templating/www/doc/design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/design.html,v diff -u -r1.4 -r1.4.2.1 --- openacs-4/packages/acs-templating/www/doc/design.html 16 Jun 2015 08:53:38 -0000 1.4 +++ openacs-4/packages/acs-templating/www/doc/design.html 22 Jun 2016 07:48:43 -0000 1.4.2.1 @@ -54,7 +54,7 @@
-
- A common solution. Programmers and designers + 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 @@ -66,8 +66,8 @@
-
- Separation of code (Tcl, Java and SQL) and layout - (HTML). Programmers should be able to specify the + 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 @@ -78,7 +78,7 @@
-
- Separation of page components. There should be + 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 @@ -90,7 +90,7 @@
-
- Global control over presentation. There should be + 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 @@ -99,7 +99,7 @@
-
- Dynamic selection of presentation style. Given + 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, @@ -110,7 +110,7 @@
-
- Usability. Programmers should be able to develop + 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 @@ -344,14 +344,14 @@
Below is a diagram of the typical call stack when processing a page without dependent pages. To conform to the Tcl notion of - what's up and down (as in upvar), the stack grows down. + what's up and down (as in upvar), the stack grows down.
@@ -485,7 +485,7 @@- Level -Procedure -Arguments +Level +Procedure +Arguments #1 rp_handler #2 rp_serve_abstract_file @@ -363,7 +363,7 @@/web/service/www/page {} (6) template::adp_prepare #5 +#5 template::code::tcl::/web/service/www/page XII. Revision History
-+
Document Revision # Action Taken, Notes Index: openacs-4/packages/acs-templating/www/doc/designer-guide.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/designer-guide.adp,v diff -u -r1.2.2.2 -r1.2.2.3 --- openacs-4/packages/acs-templating/www/doc/designer-guide.adp 9 Jun 2016 13:03:12 -0000 1.2.2.2 +++ openacs-4/packages/acs-templating/www/doc/designer-guide.adp 22 Jun 2016 07:48:43 -0000 1.2.2.3 @@ -13,11 +13,11 @@ 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). +
- 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 @@ -49,8 +49,8 @@ where users may assemble different types of content to their liking.
(graphic)
-See include and -master. See also Building reusable layout components and +
See include and +master. See also Building reusable layout components and Using master templates.
Property Declarations
Template authors need a simple mechanism for declaring @@ -60,13 +60,13 @@ include a search box. The data dictionary specifies available properties as well as the set of valid values when appropriate.
(graphic)
-See property.
+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.
+See if..else.
Iteration
Dynamic pages often present lists of values or records, each of which typically represents the results of a database query. @@ -87,9 +87,9 @@
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.
- - + +Notes
Template tags are processed by the server each time a page is @@ -102,8 +102,8 @@ 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 +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> Index: openacs-4/packages/acs-templating/www/doc/designer-guide.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/designer-guide.html,v diff -u -r1.1.1.1 -r1.1.1.1.30.1 --- openacs-4/packages/acs-templating/www/doc/designer-guide.html 13 Mar 2001 22:59:27 -0000 1.1.1.1 +++ openacs-4/packages/acs-templating/www/doc/designer-guide.html 22 Jun 2016 07:48:43 -0000 1.1.1.1.30.1 @@ -22,18 +22,18 @@
- Embed a dynamic variable in a template -(var). +(var).
- Repeat a template section for each object in a dynamic list of objects -(multiple, - grid). +(multiple, + grid).
- Output different template sections depending on the value of one or more -dynamic variables (if). +dynamic variables (if).
- Provide a mechanism for building complete pages from multiple component templates -(include). +(include).
(graphic)
-See include and master. See also See include and master. See also Building reusable layout components and Using master templates. @@ -95,7 +95,7 @@
(graphic)
-See property.
+See property.
Conditional Insertion
@@ -104,7 +104,7 @@ books that a user has checked out, the designer might want to highlight the overdue ones in red. -See if..else.
+See if..else.
Iteration
@@ -131,10 +131,10 @@ some additional variables that the designer can reference to vary the layout from item to item. -See multiple, - group, - grid.
- +See multiple, + group, + grid.
+Notes
@@ -154,7 +154,7 @@ 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) +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: @@ -169,7 +169,7 @@ template later.
- Caution: + Caution: Do not write to the connection. Specifically, if you must use the
<% %>tag, do not callns_puts, because it will not work the same way as in AOLserver's ADP Index: openacs-4/packages/acs-templating/www/doc/index.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/index.html,v diff -u -r1.6.2.2 -r1.6.2.3 --- openacs-4/packages/acs-templating/www/doc/index.html 21 Aug 2015 10:28:47 -0000 1.6.2.2 +++ openacs-4/packages/acs-templating/www/doc/index.html 22 Jun 2016 07:48:43 -0000 1.6.2.3 @@ -12,7 +12,7 @@Document overview
-+
Requirements What the template system should do for you. 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 -r1.2.2.2 -r1.2.2.3 --- openacs-4/packages/acs-templating/www/doc/install.adp 9 Jun 2016 13:03:12 -0000 1.2.2.2 +++ openacs-4/packages/acs-templating/www/doc/install.adp 22 Jun 2016 07:48:43 -0000 1.2.2.3 @@ -26,11 +26,11 @@The distribution consists of four subdirectories:
- -demo: A set of sample templates and supporting +demo: A set of sample templates and supporting files.
- -doc: Documentation and tutorials.
- -tcl: The Tcl module.
- -resources: Sitewide style templates for forms +doc: Documentation and tutorials.
- +tcl: The Tcl module.
- +resources: Sitewide style templates for forms and error messages and associated assets.
You can also untar (or check out) the distribution somewhere @@ -40,10 +40,10 @@
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 +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 +installation (as indicated by the Library parameter in the +ns/server/myserver/tcl section of the AOLserver configuration file):
$ cd /web/myserver/tcl @@ -66,7 +66,7 @@ ns_param nslog nslog.so ns_param ats Tcl
-Note that you should replace ats with whatever you +
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 @@ -82,31 +82,31 @@
Optional Configuration
The templating system recognizes two optional parameters in the AOLserver configuration file in the -ns/server/yourserver/ats section:
+ns/server/yourserver/ats section:- DatabaseInterface Specifies the set of procedures to use for accessing a + DatabaseInterface Specifies 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 +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. +generic (uses the ns_db API in conjunction with +any AOLserver RDBMS driver). The default is Oracle.- ShowCompiledTemplatesP Enables a filter on the cmp extension so that the + ShowCompiledTemplatesP Enables 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). - ShowDataDictionariesP Enables a filter on the dat extension so that + ShowDataDictionariesP Enables 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). - ResourcePath Specifies the absolute path to the system templates + ResourcePath Specifies the absolute path to the system templates directory, containing sitewide styles for forms, system messages, -etc. Defaults to $::acs::pageroot/ats/resources. +etc. Defaults to $::acs::pageroot/ats/resources.Testing the System
-To test the system, run the script demo/demo.sql to +
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 Index: openacs-4/packages/acs-templating/www/doc/install.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/install.html,v diff -u -r1.2 -r1.2.4.1 --- openacs-4/packages/acs-templating/www/doc/install.html 12 Apr 2013 16:12:57 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/install.html 22 Jun 2016 07:48:43 -0000 1.2.4.1 @@ -4,7 +4,7 @@
Installation
- Templating System + Templating System
The templating system may be used alone or in conjunction with @@ -36,10 +36,10 @@
The distribution consists of four subdirectories:
-
-
- demo: A set of sample templates and supporting files. -
- doc: Documentation and tutorials. -
- tcl: The Tcl module. -
- resources: Sitewide style templates for forms and +
- demo: A set of sample templates and supporting files. +
- doc: Documentation and tutorials. +
- tcl: The Tcl module. +
- resources: Sitewide style templates for forms and error messages and associated assets.
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 +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 +(as indicated by the Library parameter in the +ns/server/myserver/tcl section of the AOLserver configuration file):
$ cd /web/myserver/tcl @@ -69,16 +69,16 @@
[ns/server/myserver/modules] nssock=nssock.so nslog=nslog.so -ats=Tcl
+ats=Tclor 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+ns_param ats Tcl -Note that you should replace ats with whatever you named +
Note that you should replace ats with whatever you named the directory or symlink for the templating code within your private Tcl library.
@@ -96,41 +96,41 @@The templating system recognizes two optional parameters in the AOLserver configuration file in the -ns/server/yourserver/ats section:
+ns/server/yourserver/ats section: -+
- DatabaseInterface +DatabaseInterface Specifies 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 +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. +Oracle.- ShowCompiledTemplatesP -Enables a filter on the cmp extension so that the compiled + ShowCompiledTemplatesP +Enables 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). - ShowDataDictionariesP -Enables a filter on the dat extension so that documentation + ShowDataDictionariesP +Enables 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). - ResourcePath -Specifies the absolute path to the system templates directory, + ResourcePath +Specifies the absolute path to the system templates directory, containing sitewide styles for forms, system messages, etc. Defaults to -$::acs::pageroot/ats/resources. +$::acs::pageroot/ats/resources.Testing the System
-To test the system, run the script demo/demo.sql to create +
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 Index: openacs-4/packages/acs-templating/www/doc/introduction.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/introduction.html,v diff -u -r1.1.1.1 -r1.1.1.1.30.1 --- openacs-4/packages/acs-templating/www/doc/introduction.html 13 Mar 2001 22:59:27 -0000 1.1.1.1 +++ openacs-4/packages/acs-templating/www/doc/introduction.html 22 Jun 2016 07:48:43 -0000 1.1.1.1.30.1 @@ -4,7 +4,7 @@
Goals
- Templating System + Templating System
The overall goal of the templating system is to provide the @@ -13,41 +13,41 @@
-
-
A common solution. Programmers and designers should only +
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). +
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 +
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 +
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 +
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 +
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 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 -r1.3.2.9 -r1.3.2.10 --- openacs-4/packages/acs-templating/www/doc/migration.adp 9 Jun 2016 13:03:12 -0000 1.3.2.9 +++ openacs-4/packages/acs-templating/www/doc/migration.adp 22 Jun 2016 07:48:43 -0000 1.3.2.10 @@ -46,7 +46,7 @@ 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>\] +Nuts \$2.70 \[<a href="
@@ -409,15 +409,15 @@
# alert has been disabled
set status "Disabled"
set action "
- <a href=\"/bboard/alert-reenable\">
- Re-enable</a>"
+ <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>"
+ <a href="\"/bboard/alert-disable\">
+" Disable</a>"
}
append existing_alert_rows "<tr>
Index: openacs-4/packages/acs-templating/www/doc/migration.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/migration.html,v
diff -u -r1.3 -r1.3.2.1
--- openacs-4/packages/acs-templating/www/doc/migration.html 27 Oct 2014 16:40:14 -0000 1.3
+++ openacs-4/packages/acs-templating/www/doc/migration.html 22 Jun 2016 07:48:43 -0000 1.3.2.1
@@ -13,9 +13,9 @@
- Audit the template for variables that export form variables and -add ;noquote to them.
- More generally, audit the template for variables that are known +add ;noquote to them.
- 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.
- Add ;literal to variables used inside the -property tag.
- Add ;noquote to textual variables whose values are -attributes to the include tag.
- Audit the template for occurrences of -<%= [ns_quotehtml \@variable\@] => -and replace them with \@variable\@.
- Audit the Tcl code for occurrences of ns_quotehtml. If +provided by the user. Add ;noquote to them.
- Add ;literal to variables used inside the +property tag.
- Add ;noquote to textual variables whose values are +attributes to the include tag.
- Audit the template for occurrences of +<%= [ns_quotehtml \@variable\@] => +and replace them with \@variable\@.
- Audit the Tcl code for occurrences of ns_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.
- Add ;noquote to the "HTML component" variables noted +quoting.
- Add ;noquote to the "HTML component" variables noted in the previous step.
-
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 +"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. "©". This +the representation of an entity, e.g. "©". 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 "©", everything is OK. If it is listed as -"&copy;", it means that the string was quoted +as "©", everything is OK. If it is listed as +"&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 +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 +(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.
Index: openacs-4/packages/acs-templating/www/doc/no-quote-upgrade.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/no-quote-upgrade.html,v diff -u -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-templating/www/doc/no-quote-upgrade.html 20 Aug 2015 17:19:53 -0000 1.2.2.1 +++ openacs-4/packages/acs-templating/www/doc/no-quote-upgrade.html 22 Jun 2016 07:48:43 -0000 1.2.2.2 @@ -11,7 +11,7 @@ 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 + 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 @@ -31,17 +31,17 @@All variables are now quoted by default, except those explicitly - protected by ;noquote or ;literal;. + protected by ;noquote or ;literal;.
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 + ;noquote needs to be added. That's all porting effort that is required. Actually, the variables are subject to -HTML-quoting and internationalization. The suffix ;noquote +HTML-quoting and internationalization. The suffix ;noquote means that the variable's content will be internationalized, but not -HTML-quoted, while ;no18n means quote, but don't - internationalize. Finally ;literal means: don't quote and +HTML-quoted, while ;no18n means quote, but don't + internationalize. Finally ;literal means: don't quote and don't internationalize. @@ -52,20 +52,20 @@ 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 + 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 ;noquote modifier.The Most Common Cases.
- The most common cases where you need to add ;noquote to + The most common cases where you need to add ;noquote to the variable name are easy to recognize and identify.- Hidden form variables. + 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 @@ -84,7 +84,7 @@ -
Audit the template for variables that export form variables
- and add ;noquote to them.
+ and add ;noquote to them.
-
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.
+ content provided by the user. Add ;noquote to them.
-
- Add ;literal to variables used inside the
- property tag.
+ Add ;literal to variables used inside the
+ property tag.
-
- Add ;noquote to textual variables whose values are
- attributes to the include tag.
+ Add ;noquote to textual variables whose values are
+ attributes to the include tag.
-
Audit the template for occurrences of
- <%= [ns_quotehtml @variable@] =>
- and replace them with @variable@.
+ <%= [ns_quotehtml @variable@] =>
+ and replace them with @variable@.
-
- Audit the Tcl code for occurrences of ns_quotehtml.
+ Audit the Tcl code for occurrences of ns_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.
- - Add ;noquote to the "HTML component" variables noted + Add ;noquote to the "HTML component" variables noted in the previous step.
- HTML junk appearing in the page.
+ - 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. + "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.
+ 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. "©". This looks like the copyright + e.g. "©". 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 - "©", everything is OK. If it is listed as - "&copy;", it means that the string was quoted + "©", everything is OK. If it is listed as + "&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 + 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 + 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. 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 -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/requirements.html 27 Oct 2014 16:40:14 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/requirements.html 22 Jun 2016 07:48:43 -0000 1.2.2.1 @@ -21,7 +21,7 @@ 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. + name for the system is nowacs-templating.II. Vision Statement
@@ -80,19 +80,19 @@ 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 + implementing the application logic of the site, while designers are more responsible for the - presentation. Generally speaking, the application logic + 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 + 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.
@@ -102,8 +102,8 @@
-
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
+ 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
@@ -224,8 +224,8 @@
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 + 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 @@ -255,9 +255,9 @@ 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 + must have the ability to write simple program logic (Note: We run the risk of inventing our own language here, we must be - careful). + careful).
@@ -384,10 +384,10 @@
- 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. - Returns:
+
- Returns:
- The list of attributes that were added. @@ -154,7 +154,7 @@
- Options:
+
- Options:
-
description+ descriptionmime_type+ mime_typetext+ texttmpfile+ tmpfile-
+ content::add_child_relation_element @@ -233,28 +233,28 @@-
- Parameters:
+ Parameters:
- Options:
+
- Options:
-
section+ section- none If present, creates a new form section for the element. label+ label{Child relation tag} The label for the element -
+ content::add_content @@ -277,13 +277,13 @@-
- Parameters:
+ Parameters:
- Options:
+
- Options:
-
form_name+ form_nameThe name of the ATS form object. Defaults to { new_item} . content_type+ content_typeThe content_type of the item. Defaults to { content_revision} . content_method+ 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_id+ item_idThe item ID of the revision. Defaults to null (item_id must be set by the calling code). revision_id+ revision_idThe revision ID from which to draw default values. Defaults to the latest revision attributes+ attributesA list of attribute names for which to create form elements. action+ actionThe URL to which the form should redirect following a successful form submission. -
+ content::copy_content @@ -435,20 +435,20 @@-
- Parameters:
+ Parameters:
- See Also:
+
- See Also:
- add_revision -
- Options:
+
- Options:
-
form_name+ form_nameThe name of the ATS form object. Defaults to { new_item} . content_type+ content_typeThe content_type of the item. Defaults to { content_revision} . content_method+ 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_id+ parent_idThe item ID of the parent. Defaults to null (Parent is the root folder). name+ nameThe default name of the item. Default is an empty string (User must supply name). attributes+ attributesA list of attribute names for which to create form elements. action+ actionThe URL to which the form should redirect following a successful form submission. -
+ content::validate_name @@ -642,19 +642,19 @@-
- Parameters:
+ Parameters:
- Returns:
+
- Returns:
-
0 if there are items with the same name, 1 otherwise
@@ -669,8 +669,8 @@
-Private Methods:
-+Private Methods:
+content::add_revision_dml @@ -681,40 +681,40 @@-
- Parameters:
+ Parameters:
- See Also:
+
- See Also:
- add_revision -
-- statement+statement*+ The DML for the insert statement, specifying a bind variable for each column value. - bind_vars+bind_vars*+ An ns_set containing the values for all bind variables. - tmpfile+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+filename*+ The client-side name of the file containing the body of the revision to upload into the content BLOB column of cr_revisions -
+ content::attribute_insert_statement @@ -734,34 +734,34 @@-
- Parameters:
+ Parameters:
- Returns:
+
- 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. @@ -943,7 +943,7 @@
- Returns:
+
- 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. @@ -1055,7 +1055,7 @@
- content_type+content_type*+ The content type of the item for which a new revision is being prepared. - table_name+table_name*+ The storage table of the content type. - bind_vars+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].} - @@ -773,7 +773,7 @@form_name+form_name*+ The name of the ATS form object used to process the submission. -
+ content::get_attribute_params @@ -784,20 +784,20 @@-
- Parameters:
+ Parameters:
- content_type+content_type*+ The content type keyword to which this attribute belongs. - @@ -809,7 +809,7 @@attribute_name+attribute_name*+ The name of the attribute, as represented in the attribute_name column of the acs_attributes table. -
+ content::get_attributes @@ -820,20 +820,20 @@-
- Parameters:
+ Parameters:
- content_type+content_type*+ The name of the content type (ACS Object Type) for which to obtain the list of attributes. - @@ -845,7 +845,7 @@args+args*+ Names of columns to query. If no columns are specified, returns a simple list of attribute names. -
+ content::get_default_content_method @@ -856,13 +856,13 @@-
- Parameters:
+ Parameters:
- @@ -874,7 +874,7 @@content_type+content_type*+ The content type for which an input method is needed. -
+ content::get_sql_value @@ -885,20 +885,20 @@-
- Parameters:
+ Parameters:
- name+name*+ The name of the column and bind variable (they should be the same). - @@ -910,7 +910,7 @@datatype+datatype*+ The datatype of the column. -
+ content::get_type_attribute_params @@ -921,19 +921,19 @@-
- Parameters:
+ Parameters:
-- args+args*+ Any number of object types -
+ content::get_type_info @@ -954,27 +954,27 @@-
- Parameters:
+ Parameters:
- object_type+object_type*+ Object type key for which info is required. - ref+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 - @@ -986,7 +986,7 @@args+args*+ Column names to query. -
+ content::get_widget_param_value @@ -997,20 +997,20 @@-
- Parameters:
+ Parameters:
- array_ref+array_ref*+ The name of an array in the calling frame containing parameter data selected from the form metadata. - @@ -1022,7 +1022,7 @@content_type+content_type*+ The current content {type;} defaults to content_revision -
+ content::prepare_content_file @@ -1033,19 +1033,19 @@-
- Parameters:
+ Parameters:
-- form_name+form_name*+ The name of the form object in which content was submitted. -
+ content::set_attribute_values @@ -1066,34 +1066,34 @@-
- Parameters:
+ Parameters:
- form_name+form_name*+ The name of the ATS form object containing the attribute elements. - content_type+content_type*+ The type of item being revised in the form. - revision_id+revision_id*+ The revision ID from where to get the default values - @@ -1105,7 +1105,7 @@attributes+attributes*+ The list of attributes whose values should be set. -
+ content::set_content_value @@ -1116,20 +1116,20 @@-
- Parameters:
+ Parameters:
- form_name+form_name*+ The name of the ATS form object containing the content element. - @@ -1141,7 +1141,7 @@revision_id+revision_id*+ The revision ID of the content to revise -
+ content::string_to_file @@ -1152,13 +1152,13 @@-
- Parameters:
+ Parameters:
- @@ -1170,7 +1170,7 @@s+s*+ The string to write to the file. -
+ content::update_content_from_file @@ -1181,20 +1181,20 @@-
- Parameters:
+ Parameters:
- revision_id+revision_id*+ The object ID of the revision to update. - @@ -1206,7 +1206,7 @@tmpfile+tmpfile*+ The name of a temporary file containing the content. The file is deleted following the update. -
+ content::upload_content @@ -1217,34 +1217,34 @@-
- Parameters:
+ Parameters:
- db+db*+ A db handle - revision_id+revision_id*+ The revision to which the content belongs - tmpfile+tmpfile*+ The server-side name of the file containing the body of the revision to upload into the content BLOB column of cr_revisions. - @@ -1258,7 +1258,7 @@filename+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.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/content_add.html,v diff -u -r1.1.1.1 -r1.1.1.1.30.1 --- openacs-4/packages/acs-templating/www/doc/TclDocs/content_add.html 13 Mar 2001 22:59:27 -0000 1.1.1.1 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/content_add.html 22 Jun 2016 07:48:44 -0000 1.1.1.1.30.1 @@ -23,15 +23,15 @@Method Detail
-+
* indicates required
-Public Methods:
-+Public Methods:
+ - See Also:
+
-- form_name+form_name*+ The name of the form (containing name and parent_id) - Options:
- revision_id_src+revision_id_src*+ The object ID of the revision with the content to be copied. - @@ -460,7 +460,7 @@revision_id_dest+revision_id_dest*+ The object ID of the revision to be updated. copied. -
+ content::get_attribute_enum_values @@ -471,13 +471,13 @@-
- Parameters:
+ Parameters:
- @@ -489,7 +489,7 @@attribute_id+attribute_id*+ The primary key of the attribute as in the attribute_id column of the acs_attributes table. -
+ content::get_latest_revision @@ -500,13 +500,13 @@-
- Parameters:
+ Parameters:
- @@ -518,7 +518,7 @@item_id+item_id*+ The ID of the content item. -
+ content::get_object_id @@ -535,7 +535,7 @@-
+ content::new_item @@ -546,26 +546,26 @@-
- Parameters:
+ Parameters:
-- form_name+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+tmpfile*+ Name of the temporary file containing the content to upload for the initial revision. -
+ content::new_item_form @@ -585,41 +585,41 @@-
-
- Options:
- @@ -295,7 +295,7 @@revision_id+revision_id*+ The object ID of the revision to be updated. -
+ content::add_content_element @@ -306,20 +306,20 @@-
- Parameters:
+ Parameters:
- form_name+form_name*+ The name of the form to which the object should be added. - @@ -331,7 +331,7 @@content_method+content_method*+ One of no_content, text_entry or file_upload -
+ content::add_revision @@ -342,20 +342,20 @@-
- Parameters:
+ Parameters:
- form_name+form_name*+ Name of the form from which to obtain attribute values. The form should include an item_id and revision_id. - @@ -367,7 +367,7 @@tmpfile+tmpfile*+ Name of the temporary file containing the content to upload. -
+ content::add_revision_form @@ -378,41 +378,41 @@-
-
- Options:
-- form_name+form_name*+ The name of the form - Options:
In a Nutshell
When templatizing a legacy tcl page, your task is to - separate code and graphical presentation. The latter goes + 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. + 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 @@ -66,7 +66,7 @@ Remember to remove backslashes where you had to escape special characters, as inNuts \$2.70 \[<a href=\"shoppe[<a href="
@@ -90,17 +90,17 @@<form>. I reformatted it a bit to make three panes fit next to each other and to line up corresponding code. -+
- old tcl code -new +old tcl code +new packages/news/www/item-view.tclpackages/news/www/item-view.adp- + # /packages/news/admin/index.tcl ad_page_contract { @@ -148,7 +148,7 @@ return+ ad_page_contract { @@ -195,7 +195,7 @@ ad_return_template+ @@ -249,17 +249,17 @@ following example shows the part of theindexpage of the News module that uses the mechanism, not a whole page. -+
- old tcl code -new +old tcl code +new packages/news/www/index.tclpackages/news/www/index.adp- + ad_page_contract { @@ -275,7 +275,7 @@ }+ ad_page_contract { @@ -293,19 +293,19 @@ context_bar:onevalue subsite_id:onevalue subsite:multirow - item:multirow + item:multirow footer:onevalue }- ... -... -... +... +... +... - + append body " <ul> @@ -319,8 +319,8 @@ and ( expiration_date is null or expiration_date > sysdate) } { - append body "<li><a href= - \"item-view?news_item_id="\ + append body "<li><a href=" + \"item-view?news_item_id=+ -db_multirow item news_items_select { +db_multirow item news_items_select { select news_item_id, title from news_items_obj where context_id = :subsite_id @@ -357,13 +357,13 @@ }+ <ul> -<multiple name=item> +<multiple name=item> @@ -372,12 +372,12 @@ <li><a href= - "item-view?news_item_id=<% - %>@item.news_item_id@" - >@item.title@</a> + "item-view?news_item_id=<% + %>@item.news_item_id@" + >@item.title@</a> </multiple> -<if @item:rowcount@ eq 0> +<if @item:rowcount@ eq 0> <li>There are currently no news items available. @@ -423,25 +423,25 @@ output from sql and also the output of tcl procedures using that value. -+
- old tcl code -new +old tcl code +new packages/acs-core-ui/www/pvt/alerts.tclpackages/acs-core-ui/www/pvt/alerts.adp- + ad_page_contract { @cvs-id $Id$ } { }+ ad_page_contract { @cvs-id $Id$ @@ -462,11 +462,11 @@- ... -... -... +... +... +... - + @@ -494,15 +494,15 @@ # alert has been disabled set status "Disabled" set action " - <a href=\"/bboard/alert-reenable\"> - Re-enable</a>" + <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>" + <a href="\"/bboard/alert-disable\"> +" Disable</a>" } append existing_alert_rows "<tr> @@ -546,7 +546,7 @@ }+ set discussion_forum_alert_p 0 @@ -596,7 +596,7 @@
+ 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 -r1.3.2.3 -r1.3.2.4 --- openacs-4/packages/acs-templating/www/doc/no-quote-upgrade.adp 9 Jun 2016 13:03:12 -0000 1.3.2.3 +++ openacs-4/packages/acs-templating/www/doc/no-quote-upgrade.adp 22 Jun 2016 07:48:43 -0000 1.3.2.4 @@ -24,20 +24,20 @@ The change to the templating system can be expressed in one sentence:
ACS has a convenience function for creating hidden form variables, -export_form_vars +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. @@ -81,7 +81,7 @@ -The ADP will simply refer to the form_vars +The ADP will simply refer to the form_vars variable:All variables are now quoted by default, except those -explicitly protected by ;noquote or -;literal;.
+explicitly protected by ;noquote or +;literal;. 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 +;noquote needs to be added. That's all porting effort that is required. Actually, the variables are subject to HTML-quoting -and internationalization. The suffix ;noquote +and internationalization. The suffix ;noquote means that the variable's content will be internationalized, but not -HTML-quoted, while ;no18n +HTML-quoted, while ;no18n means quote, but don't -internationalize. Finally ;literal +internationalize. Finally ;literal means: don't quote and don't internationalize.This is not hard because most variables will not be affected by @@ -47,11 +47,11 @@ 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 +variables should be protected from quoting by the ;noquote modifier.
The Most Common Cases.
-The most common cases where you need to add ;noquote +The most common cases where you need to add ;noquote to the variable name are easy to recognize and identify.@@ -71,7 +71,7 @@
-This will no longer work as intended because form_vars +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 +not work. After protecting the variable with ;noquote , everything works as expected:<form> @@ -91,12 +91,12 @@
-@@ -121,7 +121,7 @@
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 +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.
@@ -132,13 +132,13 @@ 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.
+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 +addition of ;noquote . Let's review why. -The property tag is used to pass a piece of information +
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 @@ -166,14 +166,14 @@ 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 +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 +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 @@ -191,19 +191,19 @@ 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 +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 ;literal -inside the property tag rather than in the master. The +
Over-quoting is resolved by adding ;noquote to one of +the variables. We strongly recommend that you add ;literal +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 +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 +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:
@@ -216,7 +216,7 @@The exact same problems when the include statement +
The exact same problems when the include statement passes some text. Here is an example:
Including template:
Here an include statement is used to include an HTML form widget -parts of which are defined with Tcl variables $id +parts of which are defined with Tcl variables $id and -$default_reason +$default_reason whose values presumably come from the database.@@ -226,24 +226,24 @@ <form action="do-kick" method=POST> Kick user \@name\@.<br> Reason: <textarea name=reason>\@reason\@</textarea><br> - <input type=submit value="Kick"> + <input type="submit" value="Kick"> </form>What happens is that reason that prefills the -textarea is over-quoted. The reasons are the same as in +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 -;literal.
+;literal.Including template, sans over-quoting:
ACS has a convenience function for creating hidden form variables, - export_form_vars. It accepts a list of variables and + 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 @@ -96,7 +96,7 @@ - The ADP will simply refer to the form_vars variable: + The ADP will simply refer to the form_vars variable:<include src="user-kick-form" id=\@kicked_id;literal\@ reason=\@default_reason;literal\@> @@ -259,16 +259,16 @@ frequency of occurrence of the problem.
- This will no longer work as intended because form_vars + 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, + not work. After protecting the variable with ;noquote, everything works as expected:@@ -107,11 +107,11 @@@@ -124,51 +124,51 @@
- Snippets of HTML produced by Tcl code, aka - widgets. + 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 + 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 + 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 + 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 + written and that they will quote the components used to build the widget.
- Pieces of text that are already quoted. + 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 + be redundant, so we must be careful to add ;noquote to the ADP. -The property and include Gotchas.
+The property and include Gotchas.
Transfer of parameters between included ADPs often requires manual - addition of ;noquote. Let's review why. + addition of ;noquote. Let's review why.- The property tag is used to pass a piece of information + 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: + master:
<head> <title>@title@</title> @@ -178,7 +178,7 @@ <slave> </body>- slave: + slave:<master> <property name="title">@title@</property> @@ -191,15 +191,15 @@ 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. + 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 + 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. @@ -211,8 +211,8 @@ 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 + 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 @@ -221,34 +221,34 @@
- This occurrence is often referred to as over-quoting. + 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 + 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 + Over-quoting is resolved by adding ;noquote to one of the variables. We strongly recommend that you add - ;literal inside the property tag rather than + ;literal 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 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 + 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: + slave sans over-quoting:
<master> <property name="doc(title)">@title;literal@</property> @@ -258,39 +258,39 @@- The exact same problems when the include statement + The exact same problems when the include statement passes some text. Here is an example:
- Including template: + Including template:
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 + parts of which are defined with Tcl variables $id and + $default_reason whose values presumably come from the database.<include src="user-kick-form" id=@kicked_id@ reason=@default_reason@>- Included template: + Included template:<form action="do-kick" method=POST> Kick user @name@.<br> Reason: <textarea name=reason>@reason@</textarea><br> - <input type=submit value="Kick"> + <input type="submit" value="Kick"> </form>What happens is that reason that prefills the - textarea is over-quoted. The reasons are the same as + 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 ;literal. + sure to add ;literal.
- Including template, sans over-quoting: + Including template, sans over-quoting:
<include src="user-kick-form" id=@kicked_id;literal@ reason=@default_reason;literal@>@@ -307,34 +307,34 @@-
-
VII. Revision History
--
- Document Revision # -Action Taken, Notes ++
+ Index: openacs-4/packages/acs-templating/www/doc/timing-1.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/timing-1.html,v diff -u -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/timing-1.html 27 Oct 2014 16:40:14 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/timing-1.html 22 Jun 2016 07:48:43 -0000 1.2.2.1 @@ -79,13 +79,13 @@Document Revision # +Action Taken, Notes When? By Whom? Invoking trace filter ds_trace_filter
- That last phase is ended by - Done invoking trace filter ds_trace_filter (returning filter_ok) + 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 + 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. Index: openacs-4/packages/acs-templating/www/doc/timing-2.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/timing-2.html,v diff -u -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/timing-2.html 27 Oct 2014 16:40:15 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/timing-2.html 22 Jun 2016 07:48:43 -0000 1.2.2.1 @@ -13,7 +13,7 @@
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 + 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 @@ -42,7 +42,7 @@
Overall, the templated pages are delivered markedly - slower, by about 65ms. + 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. Index: openacs-4/packages/acs-templating/www/doc/timing-3.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/timing-3.html,v diff -u -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/timing-3.html 27 Oct 2014 16:40:15 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/timing-3.html 22 Jun 2016 07:48:43 -0000 1.2.2.1 @@ -46,8 +46,8 @@
- In ACS 3.4.6, Tcl-only pages are sereved faster than in - 4.0 beta-2. The templated pages are delivered much slower. + 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. Index: openacs-4/packages/acs-templating/www/doc/timing.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/timing.html,v diff -u -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/timing.html 27 Oct 2014 16:40:15 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/timing.html 22 Jun 2016 07:48:43 -0000 1.2.2.1 @@ -38,15 +38,15 @@ into continued fractions. I created three versions:
-
-
Color Codes
The different experiments are color coded as follows. -
+
never normal always chain-frac-0 Index: openacs-4/packages/acs-templating/www/doc/TclDocs/cm_widget.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/cm_widget.html,v diff -u -r1.1.1.1 -r1.1.1.1.30.1 --- openacs-4/packages/acs-templating/www/doc/TclDocs/cm_widget.html 13 Mar 2001 22:59:27 -0000 1.1.1.1 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/cm_widget.html 22 Jun 2016 07:48:43 -0000 1.1.1.1.30.1 @@ -23,7 +23,7 @@Method Detail
-+
* indicates required
@@ -32,10 +32,10 @@-Private Methods:
-+Private Methods:
+cm_widget::validate_description -
by Michael Pih +
by Michael Pih@@ -44,13 +44,13 @@ -
- Parameters:
+ Parameters:
- @@ -64,7 +64,7 @@value+value*+ The submitted value of the description form element -
+
* indicates required
Index: openacs-4/packages/acs-templating/www/doc/TclDocs/cms_rel.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/cms_rel.html,v diff -u -r1.1.1.1 -r1.1.1.1.30.1 --- openacs-4/packages/acs-templating/www/doc/TclDocs/cms_rel.html 13 Mar 2001 22:59:27 -0000 1.1.1.1 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/cms_rel.html 22 Jun 2016 07:48:43 -0000 1.1.1.1.30.1 @@ -25,15 +25,15 @@Method Detail
-+
* indicates required
-Public Methods:
-+Public Methods:
+cms_rel::sort_child_item_order -
by Michael Pih +
by Michael Pih@@ -42,13 +42,13 @@ -
- Parameters:
+ Parameters:
- @@ -60,9 +60,9 @@item_id+item_id*+ The item for which to resort child items -
+ cms_rel::sort_related_item_order -
by Michael Pih +
by Michael Pih@@ -71,13 +71,13 @@ -
- Parameters:
+ Parameters:
- @@ -95,7 +95,7 @@ -item_id+item_id*+ The item for which to resort related items +
* indicates required
Index: openacs-4/packages/acs-templating/www/doc/TclDocs/content.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/content.html,v diff -u -r1.1.1.1 -r1.1.1.1.30.1 --- openacs-4/packages/acs-templating/www/doc/TclDocs/content.html 13 Mar 2001 22:59:27 -0000 1.1.1.1 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/content.html 22 Jun 2016 07:48:43 -0000 1.1.1.1.30.1 @@ -51,13 +51,13 @@Method Detail
-+
* indicates required
-Public Methods:
-+Public Methods:
+content::add_attribute_element @@ -68,34 +68,34 @@-
- Parameters:
+ Parameters:
- form_name+form_name*+ The name of the ATS form object to which the element should be added. - content_type+content_type*+ The content type keyword to which this attribute belongs. - attribute+attribute*+ The name of the attribute, as represented in the attribute_name column of the acs_attributes table. - @@ -107,7 +107,7 @@attribute_data+attribute_data*+ Optional nested list of parameter data for the the attribute (generated by get_attribute_params). -
+ content::add_attribute_elements @@ -118,33 +118,33 @@-
- Parameters:
+ Parameters:
-- form_name+form_name*+ The name of the ATS form object to which objects should be added. - content_type+content_type*+ The content type keyword for which attribute widgets should be added. - revision_id+revision_id*+ The revision from which default values should be queried -
+ content::add_basic_revision @@ -165,52 +165,52 @@-
- Parameters:
+ Parameters:
-- item_id+item_id*+ - revision_id+revision_id*+ - title+title*+