-
@@ -61,14 +61,10 @@
External
@@ -16,5 +14,8 @@
Design
Release Notes
Please file bugs in the Bug Tracker.
docs\@openacs.org - +
Release Notes
+Please file bugs in the Bug Tracker.
++docs\@openacs.org Index: openacs-4/packages/acs-automated-testing/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-automated-testing/www/doc/index.adp,v diff -u -N -r1.2.2.3 -r1.2.2.4 --- openacs-4/packages/acs-automated-testing/www/doc/index.adp 21 Aug 2015 10:49:19 -0000 1.2.2.3 +++ openacs-4/packages/acs-automated-testing/www/doc/index.adp 25 Aug 2015 18:02:01 -0000 1.2.2.4 @@ -2,11 +2,11 @@
Automated Testing
Release Notes
Please file bugs in the Bug Tracker.
docs\@openacs.org - +Release Notes
+Please file bugs in the Bug Tracker.
+docs\@openacs.org Index: openacs-4/packages/acs-automated-testing/www/doc/install.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-automated-testing/www/doc/install.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-automated-testing/www/doc/install.adp 20 Aug 2015 17:19:48 -0000 1.2.2.1 +++ openacs-4/packages/acs-automated-testing/www/doc/install.adp 25 Aug 2015 18:02:02 -0000 1.2.2.2 @@ -2,11 +2,11 @@Automated Testing is part of acs-core, and therefore should already be installed in any OpenACS system. Individual automated tests are stored within each package in package/tcl/test.
-Content Repository Design
I. Essentials
II. Introduction
Serving content is a basic function of any web site. -Common types of content include:
-
+
- Journal articles and stories
- Documentation
- News reports
- Product reviews
- Press releases
- Message board postings
- Photographs -
Content Repository Design
+I. Essentials
+ +II. Introduction
+Serving content is a basic function of any web site. +Common types of content include:
+Note that the definition of content is not limited to what is +
Note that the definition of content is not limited to what is produced by the publisher. User-contributed content such as reviews, comments, or message board postings may come to dominate -active community sites.
Regardless of its type or origin, it is often useful for +active community sites.
+Regardless of its type or origin, it is often useful for developers, publishers and users to handle all content in a consistent fashion. Developers benefit because they can base all their content-driven applications on a single core API, thereby @@ -20,28 +25,36 @@ the same management and production practices, including access control, workflow, categorization and syndication. Users benefit because they can enjoy a single interface for searching, browsing -and managing their own contributions.
The content repository itself is intended only as a +and managing their own contributions.
+The content repository itself is intended only as a common substrate for developing content-driven applications. It provides the developer with a core set of content-related -services:
-
+services:
+
- Defining arbitrary content types.
- Common storage of content items (each item consists of a text or binary data with additional attributes as specified by the content type).
- Establishing relationships among items of any type.
- Versioning
- Consistent interaction with other services included in the ACS core, including permissions, workflow and object relationships.
- Categorization
- Searching -
As a substrate layer, the content repository is not intended to +
As a substrate layer, the content repository is not intended to ever have its own administrative or user interface. ACS modules and custom applications built on the repository remain responsible for implementing an appropriate interface. (Note that the ACS Content Management System provides a general interface for interacting with -the content repository).
III. Historical Considerations
The content repository was originally developed in the Spring of +the content repository).
+III. Historical Considerations
+The content repository was originally developed in the Spring of 2000 as a standalone data model. It was based on an earlier custom system developed for an ArsDigita client. Many of the principle design features of the original data model were also reflected in the ACS Objects system implemented in the ACS 4.0 core. The content repository was subsequently rewritten as an extension of ACS -Objects.
V. Design Tradeoffs
The content repository is a direct extension of the core ACS -Object Model. As such the same design tradeoffs apply.
The content repository stores all revisions of all content items +Objects.
+V. Design Tradeoffs
+The content repository is a direct extension of the core ACS +Object Model. As such the same design tradeoffs apply.
+The content repository stores all revisions of all content items in a single table, rather than maintaining separate tables for "live" and other revisions. The single-table approach dramatically simplifies most operations on the repository, including adding @@ -56,11 +69,16 @@ arrangement is minimized by storing the actual content data in a separate tablespace (preferably on a separate disk) from the actual revisions table, reducing its size and allows the database server -to scan and read it more efficiently.
VI. Further Reading
The Object Model provides a +to scan and read it more efficiently.
+VI. Further Reading
+The Object Model provides a graphic overview of the the how the content repository is designed. The model links to pages of the API Guide that describe individual objects. The Developer Guide describes how to address common -development tasks using the content repository.
karlg\@arsdigita.com
+development tasks using the content repository. +
+karlg\@arsdigita.com +
+ Last Modified: $Id: design.html,v 1.1.1.1 2001/03/13 22:59:26 ben Exp $ - Index: openacs-4/packages/acs-content-repository/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/index.adp,v diff -u -N -r1.2.2.6 -r1.2.2.7 --- openacs-4/packages/acs-content-repository/www/doc/index.adp 21 Aug 2015 10:49:19 -0000 1.2.2.6 +++ openacs-4/packages/acs-content-repository/www/doc/index.adp 25 Aug 2015 18:02:02 -0000 1.2.2.7 @@ -2,9 +2,8 @@
ACS Content Repository
-
+
ACS Content Repository
+Release Notes
Please file bugs in the Bug Tracker.
karlg\@arsdigita.com
-Last Revised: $Id: index.html,v 1.2.18.1 2015/08/21 10:28:44 +
Release Notes
+Please file bugs in the Bug Tracker.
++karlg\@arsdigita.com +
+ +Last Revised: $Id: index.html,v 1.2.18.2 2015/08/21 10:49:20 gustafn Exp $ - Index: openacs-4/packages/acs-content-repository/www/doc/install.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/install.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-content-repository/www/doc/install.adp 20 Aug 2015 17:19:49 -0000 1.2.2.1 +++ openacs-4/packages/acs-content-repository/www/doc/install.adp 25 Aug 2015 18:02:02 -0000 1.2.2.2 @@ -2,42 +2,57 @@
Installing the Content Repository
The content repository is a part of the core data model of ACS +
Installing the Content Repository
+The content repository is a part of the core data model of ACS 4.0 and greater, and is loaded automatically as part of the ACS -installation process.
If you wish to install the content repository in a database +installation process.
+If you wish to install the content repository in a database schema outside the context of ACS, the following instructions -apply.
First install the data model and PL/SQL API:
-
+apply.
+
- Obtain the latest distribution of ACS.
- Run the SQL script packages/acs-kernel/sql/acs-kernel-create.sql to load the core ACS Objects data model.
- Run the SQL script packages/acs-workflow/sql/acs-workflow-create.sql to load the workflow package.
- Run the SQL script packages/acs-workflow/sql/acs-content-repository-create.sql to load the content repository itself. -
First install the data model and PL/SQL API:
+Java
In additional to SQL and PL/SQL, the content repository +
Java
+In additional to SQL and PL/SQL, the content repository implements a limited set of key methods in Java. The XML import and export methods are dependent on Oracle's XML Parser for Java v2, -available from the Oracle Technology Network:
http://technet.us.oracle.com/tech/xml/parser_java2/index.htmTo load the XML parser, download and untar the distribution. +available from the Oracle Technology Network:
+http://technet.us.oracle.com/tech/xml/parser_java2/index.htm +To load the XML parser, download and untar the distribution. Load the class package lib/xmlparserv2.jar into Oracle -from a shell prompt:
+from a shell prompt: ++$ loadjava -user user/password xmlparserv2.jar -Finally, load the SQLJ files in -packages/acs-content-repository/java:
++Finally, load the SQLJ files in +packages/acs-content-repository/java:
+$ loadjava -user user/password -resolve *.sqlj -Installation of the data model and API should now be -complete.
Intermedia
The content repository relies on an Intermedia with the INSO +
Installation of the data model and API should now be +complete.
+Intermedia
+The content repository relies on an Intermedia with the INSO filtering option to search text within a wide variety of file formats, including PDF and Microsoft Word. When the index on the content column of cr_revisions is built, the INSO filter automatically detects the file type of each entry and -extracts all available text for indexing.
If your searches are not returning any results even after +extracts all available text for indexing.
+If your searches are not returning any results even after rebuilding the index, INSO filtering may be silently failing. You can verifying this by checking for entries in the ctx_user_index_errors view following an alter -index statement.
If you experience errors on a UNIX system, check the -following:
-
+index statement.
+
- The operating system user running the Oracle database must have execute permission on the files $ORACLE_HOME/ctx/lib/*.flt.
- The directory $ORACLE_HOME/ctx/lib must be in the @@ -47,17 +62,22 @@ Oracle database.
- The LD_LIBRARY_PATH environment variable must be specified in the entry for PLSExtProc in the $ORACLE_HOME/network/admin/listener.ora. For example: -
If you experience errors on a UNIX system, check the +following:
++ ++(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 +
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
+content repository data model itself. +
+karlg\@arsdigita.com +
+ Last revised: $Id: install.html,v 1.1.1.1 2001/03/13 22:59:26 ben Exp $ - Index: openacs-4/packages/acs-content-repository/www/doc/intermedia.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/intermedia.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-content-repository/www/doc/intermedia.adp 20 Aug 2015 17:19:49 -0000 1.2.2.1 +++ openacs-4/packages/acs-content-repository/www/doc/intermedia.adp 25 Aug 2015 18:02:02 -0000 1.2.2.2 @@ -2,35 +2,45 @@
Testing Intermedia
Even if you follow the instructions in the installation notes, content searches may +
Testing Intermedia
+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:
+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:
++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:
++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 +
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:
+cr-test-docs.ctl: ++load data INFILE 'cr-test-docs.data' INTO TABLE cr_test_documents @@ -41,30 +51,40 @@ title, ext_fname FILLER CHAR(80), doc LOBFILE(ext_fname) TERMINATED BY EOF) -Copy any number of documents (Microsoft Word, PDF, text, HTML, +
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:
+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:
++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:
++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
+
+karlg\@arsdigita.com +
+ Last revised: $Id: intermedia.html,v 1.1.1.1 2001/03/13 22:59:26 ben Exp $ - Index: openacs-4/packages/acs-content-repository/www/doc/object-model.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/object-model.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-content-repository/www/doc/object-model.adp 20 Aug 2015 17:19:49 -0000 1.2.2.1 +++ openacs-4/packages/acs-content-repository/www/doc/object-model.adp 25 Aug 2015 18:02:02 -0000 1.2.2.2 @@ -2,26 +2,32 @@
Object Model
The content repository is an extension of the ACS Object Model. +
Object Model
+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 +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
+necessary to create a custom subtype of Content Item itself. +
+karlg\@arsdigita.com +
+ Last revised: $Id: object-model.html,v 1.1.1.1 2001/03/13 22:59:26 ben Exp $ - Index: openacs-4/packages/acs-content-repository/www/doc/requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/requirements.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-content-repository/www/doc/requirements.adp 20 Aug 2015 17:19:49 -0000 1.2.2.1 +++ openacs-4/packages/acs-content-repository/www/doc/requirements.adp 25 Aug 2015 18:02:02 -0000 1.2.2.2 @@ -2,20 +2,28 @@
Content Repository Requirements
-Karl Goldstein (karlg\@arsdigita.com)Revision History
VI.A Requirements: Data Model
The content repository must be able to store objects in any
+
+Karl Goldstein (karlg\@arsdigita.com
+)
+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 +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. Attributes are stored separately from their associated content object, and as such may be indexed, searched, sorted and retrieved independently. For example, attributes of a press release may -include a title, byline, and publication date.
The data model must support storage of descriptive information -for each content type:
+include a title, byline, and publication date. ++ +The data model must support storage of descriptive information +for each content type:
+10.10 Content types must be associated with unique keyword identifiers, such as press_release, so they can be @@ -45,13 +53,17 @@ 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 +
Items are the fundamental building blocks of the content repository. Each item represents a distinct text or binary content object that is publishable to the web, such as an article, report, message or photograph. An item my also include any number of attributes with more structured data, such as title, source, byline -and publication date.
Content items have the following persistent characteristics -which the data model must support:
+and publication date. ++ +Content items have the following persistent characteristics +which the data model must support:
+20.10 Content items must have a simple unique identifier so they can be related to other objects in the system.
@@ -91,10 +103,13 @@ 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 +
As mentioned above, each content item may be associated with any number of revisions. The data model for revisions must support the -following:
+following: +30.10. A revision consists of the complete state of the item as it existed at a certain point in time. This includes the @@ -103,8 +118,10 @@ 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 organization of content items in a manner similar to a file @@ -148,19 +165,26 @@ label, which may be different from the title or label of the target item.
The content repository should provide a means of storing and + +
+The content repository should provide a means of storing and managing the templates that are merged with content items to render output in HTML or other formats. Templates are assumed to be text files containing static markup with embedded tags or code to incorporate dynamic content in appropriate places. The data model requirements for templates are a subset of those for content -items.
Because they typically need to reference a specific attributes, +items.
+Because they typically need to reference a specific attributes, a template is typically specific to a particular content types and -its subtypes.
VI.B Requirements: Stored Procedure API
100.10 MIME Types
Since a MIME type is a required attribute of each content item, +its subtypes.
+VI.B Requirements: Stored Procedure API
+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.
+content. ++100.10.10. Register a MIME type
100.10.20. Set the description of a MIME type
@@ -169,22 +193,29 @@ 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 +
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.
100.20 Locales
The repository must have access to a list of recognized locales +text/plain.
+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 character sets.
All content in the repository is stored in UTF-8 to facilitate +and character sets.
+All content in the repository is stored in UTF-8 to facilitate searching and uniform handling of content. Locales may be specified as user preferences to configure the user interface in the -following ways:
-
+following ways:
+
- language of content (when items are available in multiple languages).
- language of system messages (form labels, warnings, menu links, etc.).
- character set (text content converted from UTF-8 to the specified character set).
- number, date and currency format.
- choice of layout, including templates, graphics and other resources. -
Functional requirements for locales include:
+
Functional requirements for locales include:
+100.20.10. Register a locale, including language, territory and character set.
@@ -197,7 +228,9 @@ locale (character set).
100.20.50. Get a list of registered locales.
100.20.60. Unregister a locale.
-
100.30 Content Types
++
100.30 Content Types
+100.30.10. Create a content type, optionally specifying that it inherits the attributes of another content type. Multiple @@ -226,7 +259,9 @@ 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 the root of the repository by default.
@@ -261,9 +296,12 @@ modifying user, date modified and comments.
100.40.95. Revert to an older revision (create a new revision based on an older revision).
-
100.50 Content Folders
The repository should allow for hierarchical arrangement of + +
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 folders:
+this general requirement focuses primarily on content folders: ++100.50.10. Create a folder for logical groups of content items and other folders. The folder name becomes part of @@ -286,13 +324,19 @@ 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.
-Note that folders are simply a special type of content item, and +
Note that folders are simply a special type of content item, and as such may receive the same object services as items, (namely access control and workflow). In addition to the file-system analogy afforded by folders, any type of content item may serve as -a contain for other content items (see below).
Workflow
The repository must offer integration with a workflow package -for managing the content production process.
100.60 Categorization
The repository must support a common hierarchical taxonomy of -subject classifications that may be applied to content items.
+a contain for other content items (see below). ++Workflow
+The repository must offer integration with a workflow package +for managing the content production process.
+100.60 Categorization
+The repository must support a common hierarchical taxonomy of +subject classifications that may be applied to content items.
+100.60.10. Create a new subject category.
100.60.20. Create a new subject category as the child of @@ -302,11 +346,19 @@ 100.60.40. Remove a subject category from an item.
100.60.50. Get the subject categories assigned to a content item.
-Search
The repository must have a standard means of indexing and -searching all content.
Access Control
The repository must have a means of restricting access on an -item-by-item basis.
VI.C Requirements: Presentation Layer API
The presentation layer must have access to a subset of the +
Search
+The repository must have a standard means of indexing and +searching all content.
+Access Control
+The repository must have a means of restricting access on an +item-by-item basis.
+VI.C Requirements: Presentation Layer API
+The presentation layer must have access to a subset of the stored procedure API in order to search and retrieve content -directly from the repository if desired.
Revision History
| Author | Date | Description |
|---|---|---|
| Karl Goldstein | 21 September 2000 | Add requirements for relationships among content items and other objects. |
karlg\@arsdigita.com
+
+karlg\@arsdigita.com +
+ Last Modified: $Id: requirements.html,v 1.2 2003/12/11 21:39:47 jeffd Exp $ - Index: openacs-4/packages/acs-content-repository/www/doc/todo.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/todo.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-content-repository/www/doc/todo.adp 27 Oct 2014 16:39:13 -0000 1.2 +++ openacs-4/packages/acs-content-repository/www/doc/todo.adp 25 Aug 2015 18:02:02 -0000 1.2.2.1 @@ -2,10 +2,9 @@
To Do List for Content Management System
+- -+To Do List for Content Management System
- Documentation Write ASAP. @@ -70,6 +69,6 @@ --think about improving UI for this. 2 -Last Modified: $Id: todo.html,v 1.1.1.1 2001/03/13 22:59:26 ben +
Last Modified: $Id: todo.html,v 1.1.1.1 2001/03/13 22:59:26 ben Exp $
- Index: openacs-4/packages/acs-content-repository/www/doc/tutorial.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/tutorial.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-content-repository/www/doc/tutorial.adp 27 Oct 2014 16:39:13 -0000 1.2 +++ openacs-4/packages/acs-content-repository/www/doc/tutorial.adp 25 Aug 2015 18:02:02 -0000 1.2.2.1 @@ -2,67 +2,88 @@How to use the content repository
-by Jade RubickWhy use the content repository?
Let's say you're a developer making a package for OpenACS. + +by Jade Rubick +
Why use the content repository?
+Let's say you're a developer making a package for OpenACS. You've heard statements like, "every package should use the content repository", or maybe a developer has suggested that you use it. Or maybe you just stumbled across it. Why would you want to spend your time reading this document and wasting a good afternoon when you -could get started coding right away?
The simple answer is that the content repository (CR) gives you -many different things for free:
-
+could get started coding right away?
+
- support for versioning
- hierarchical organization of items
- permissions
- extending your tables dynamically
- What attributes do you want?
- Define tables
- Describe attributes -
- Content Type
- A set of attributes that may be associated with a text or
binary content object. For example, a press_release content type
may include a title, byline, and publication date. These attributes
are stored in the
cr_revisionstable, and a table that you set up to store specialized data. In this case, the title (I think), byline, and publication date would be stored in a specialized table.
- - Content Item
- Items are the fundamental building blocks of the content repository. Each item represents a distinct text or binary content object that is publishable to the web, such as an article, report, message or photograph. An item my also include any number of attributes with more structured data, such as title, source, byline and publication date. -
- Content Revision
- 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. -
- Content Folder
- 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. -
- Symbolic Link
- Analogous to a symlink, alias or shortcut in a file system. Allows an item to be accessed from multiple folders. -
- Templates
- Templates are merged with content items to render output in HTML or other formats. Templates are assumed to be text files containing static markup with embedded tags or code to incorporate dynamic content in appropriate places. -
- Drops the attribute storage tables for all content types you have defined.
- Drops the general tables for the content repository. -
- It does not delete rows from the acs_objects table. Many other tables reference the object_id column in this table, so there is the possibility that the uninstall script will encounter foreign key reference errors.
- It does not delete types from the acs_object_types table. As for objects themselves, it is impossible for an automatic script to properly handle disposal of all foreign key references. -
- Function content.blob_to_string
- Function content.blob_to_string
- Procedure content.blob_to_file
- Procedure content.blob_to_file
- Procedure content.string_to_blob
- Procedure content.string_to_blob
- Procedure content.string_to_blob_size
- Procedure content.string_to_blob_size
-
+
+API
+- Function: -content_extlink.is_extlink
Determines if the item is a extlink
+content_extlink.is_extlink +
Determines if the item is a extlink
+Author: Karl Goldstein @@ -31,9 +42,13 @@ See Also: content_extlink.new, content_extlink.resolve - -Function: content_extlink.new
Create a new extlink, an item pointing to an off-site -resource
+
+
+- +Function: content_extlink.new
Create a new extlink, an item pointing to an off-site +resource
+Author: Karl Goldstein @@ -82,8 +97,12 @@ See Also: acs_object.new, content_item.new, content_extlink.resolve - -Procedure: content_extlink.delete
Deletes the extlink
+
+
+- +Procedure: content_extlink.delete
Deletes the extlink
+
+Author: Karl Goldstein Parameters: @@ -96,7 +115,8 @@ See Also: content_extlink.new, acs_object.delete
+
+ Last Modified: $Id: extlink.html,v 1.1.1.1 2001/03/13 22:59:26 ben Exp $ - Index: openacs-4/packages/acs-content-repository/www/doc/api/folder.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/api/folder.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-content-repository/www/doc/api/folder.adp 27 Oct 2014 16:39:14 -0000 1.2 +++ openacs-4/packages/acs-content-repository/www/doc/api/folder.adp 25 Aug 2015 18:02:03 -0000 1.2.2.1 @@ -2,24 +2,35 @@{/doc/acs-content-repository {Content Repository}} {Package: content_folder} Package: content_folder - - - content_folder
+
content_folder
+Content Repository : -content_folder
-
+content_folder
+
+Overview
Content folders contain related content items and allow content +
+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
+"/movies/terminator2" respectively). +
+Related Objects
+ See also: Content Item -API
-
+
+API
+- Function: -content_folder.get_index_page
Returns the item ID of the index page of the folder, null -otherwise
+content_folder.get_index_page +
+Returns the item ID of the index page of the folder, null +otherwise
+Author: Michael Pih @@ -32,9 +43,13 @@ ) return cr_items.item_id%TYPE; -- -Function: content_folder.get_label
Returns the label for the folder. This function is the default -name method for the folder object.
+
+
+- +Function: content_folder.get_label
Returns the label for the folder. This function is the default +name method for the folder object.
+Author: Karl Goldstein @@ -50,8 +65,12 @@ -See Also: acs_object_type.create_type, the docs for the name_method parameter - -Function: content_folder.is_empty
Determine if the folder is empty
+
+
+- +Function: content_folder.is_empty
Determine if the folder is empty
+Author: Karl Goldstein @@ -67,8 +86,12 @@ See Also: content_folder.is_folder - -Function: content_folder.is_folder
Determine if the item is a folder
+
+
+- +Function: content_folder.is_folder
Determine if the item is a folder
+Author: Karl Goldstein @@ -83,11 +106,15 @@ See Also: content_folder.new, content_folder.is_sub_folder - +
+- Function: -content_folder.is_registered
change this to is_type_registered Determines if a content type +content_folder.is_registered
change this to is_type_registered Determines if a content type is registered to the folder Only items of the registered type(s) -may be added to the folder.
+may be added to the folder. +
+Author: Karl Goldstein @@ -114,11 +141,15 @@ -See Also: content_folder.register_content_type, content_folder.unregister_content_type, - +
+- Function: -content_folder.is_sub_folder
Determine if the item target_folder_id is a subfolder +content_folder.is_sub_folder +
Determine if the item target_folder_id is a subfolder of the item folder_id -
+ +
+Author: Karl Goldstein @@ -139,8 +170,12 @@ See Also: content_folder.is_folder - -Function: content_folder.new
Create a new folder
+
+
+- +Function: content_folder.new
Create a new folder
+Author: Karl Goldstein @@ -185,11 +220,15 @@ See Also: acs_object.new, content_item.new - -Procedure: content_folder.copy
Recursively copy the folder and all items in into a new +
+- +Procedure: content_folder.copy
Recursively copy the folder and all items in into a new location. An error is thrown if either of the parameters is not a folder. The root folder of the sitemap and the root folder of the -templates cannot be copied
+templates cannot be copied +
+Author: Karl Goldstein Parameters: @@ -207,9 +246,13 @@
See Also: content_folder.new, content_folder.copy - -Procedure: content_folder.delete
Delete a folder. An error is thrown if the folder is not -empty
+
+
+- +Procedure: content_folder.delete
Delete a folder. An error is thrown if the folder is not +empty
+
+Author: Karl Goldstein Parameters: @@ -222,11 +265,15 @@ See Also: acs_object.delete, content_item.delete - -Procedure: content_folder.move
Recursively move the folder and all items in into a new +
+- +Procedure: content_folder.move
Recursively move the folder and all items in into a new location. An error is thrown if either of the parameters is not a folder. The root folder of the sitemap and the root folder of the -templates cannot be moved.
+templates cannot be moved. +
+
+Author: Karl Goldstein Parameters: @@ -244,11 +291,15 @@
See Also: content_folder.new, content_folder.copy - +
+- Procedure: -content_folder.register_content_type
Register a content type to the folder, if it is not already +content_folder.register_content_type +
Register a content type to the folder, if it is not already registered. Only items of the registered type(s) may be added to -the folder.
+the folder. +
+Author: Karl Goldstein Parameters: @@ -268,8 +319,12 @@
See Also: content_folder.unregister_content_type, content_folder.is_registered -- -Procedure: content_folder.edit_name
Change the name, label and/or description of the folder
+
+
+- +Procedure: content_folder.edit_name
Change the name, label and/or description of the folder
+
+Author: Karl Goldstein Parameters: @@ -297,12 +352,16 @@
See Also: content_folder.new - +
+- Procedure: -content_folder.unregister_content_type
Unregister a content type from the folder, if it has been +content_folder.unregister_content_type +
Unregister a content type from the folder, if it has been registered. Only items of the registered type(s) may be added to the folder. If the folder already contains items of the type to be -unregistered, the items remain in the folder.
+unregistered, the items remain in the folder. +
+
+Author: Karl Goldstein Parameters: @@ -325,7 +384,8 @@
See Also: content_folder.register_content_type, content_folder.is_registered -
+
+ Last Modified: $Id: folder.html,v 1.2 2004/06/01 22:54:18 donb Exp $ - Index: openacs-4/packages/acs-content-repository/www/doc/api/item.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/api/item.adp,v diff -u -N -r1.2.2.6 -r1.2.2.7 --- openacs-4/packages/acs-content-repository/www/doc/api/item.adp 21 Aug 2015 10:49:20 -0000 1.2.2.6 +++ openacs-4/packages/acs-content-repository/www/doc/api/item.adp 25 Aug 2015 18:02:03 -0000 1.2.2.7 @@ -2,26 +2,37 @@{/doc/acs-content-repository {Content Repository}} {Package: content_item} Package: content_item - - - content_item
+
content_item
+Content Repository : -content_item
-
+content_item
+
+Overview
Content items store the overview of the content published on a +
+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
+content. +
+Related Objects
+ See also: content_revision, content_folder -API
-
+
+API
+- Function: -content_item.get_content_type
Retrieve the content type of this item. Only objects of this -type may be used as revisions for the item.
+content_item.get_content_type +
+Retrieve the content type of this item. Only objects of this +type may be used as revisions for the item.
+Author: Karl Goldstein @@ -34,8 +45,12 @@ ) return cr_items.content_type%TYPE; -- -Function: content_item.get_context
Retrieve the parent of the given item
+
+
+- +Function: content_item.get_context
Retrieve the parent of the given item
+Author: Karl Goldstein @@ -48,11 +63,15 @@ ) return acs_objects.context_id%TYPE; -- -Function: content_item.get_id
Takes in a path, such as "/tv/programs/star_trek/episode_203" +
+- +Function: content_item.get_id
Takes in a path, such as "/tv/programs/star_trek/episode_203" and returns the id of the item with this path. Note: URLs are abstract (no extensions are allowed in content item names and -extensions are stripped when looking up content items)
+extensions are stripped when looking up content items) +
+Author: Karl Goldstein @@ -74,10 +93,14 @@ See Also: content_item.get_path - +
+- Function: -content_item.get_latest_revision
Retrieves the id of the latest revision for the item (as opposed -to the live revision)
+content_item.get_latest_revision +
+Retrieves the id of the latest revision for the item (as opposed +to the live revision)
+Author: Karl Goldstein @@ -93,12 +116,17 @@ See Also: content_item.get_live_revision - +
+- Function: -content_item.get_live_revision
Retrieves the id of the live revision for the item
Note that this function does nothing else besides retrieving the +content_item.get_live_revision
Retrieves the id of the live revision for the item
+Note that this function does nothing else besides retrieving the value of the column
cr_items.live_revision. It is thus more efficient in many cases to join againstcr_items-and retrieve the value directly.+and retrieve the value directly. +
+Returns: The id of the live revision for this item, or null if no live revision exists @@ -113,9 +141,13 @@See Also: content_item.set_live_revision, content_item.get_latest_revision - +
+- Function: -content_item.get_parent_folder
Get the parent folder.
+content_item.get_parent_folder +
+Get the parent folder.
+Author: Michael Pih @@ -129,9 +161,13 @@ ) return cr_folders.folder_id%TYPE; -- -Function: content_item.get_path
Retrieves the full path to an item, in the form of -"/tv/programs/star_trek/episode_203"
+
+
+- +Function: content_item.get_path
Retrieves the full path to an item, in the form of +"/tv/programs/star_trek/episode_203"
+Author: Karl Goldstein @@ -152,9 +188,13 @@ See Also: content_item.get_id, content_item.write_to_file - +
+- Function: -content_item.get_publish_date
Retrieves the publish date for the item
+content_item.get_publish_date +
+Retrieves the publish date for the item
+Author: Karl Goldstein @@ -177,9 +217,13 @@ -See Also: content_item.get_live_revision, content_item.get_latest_revision, - +
+- Function: -content_item.get_revision_count
Return the total count of revisions for this item
+content_item.get_revision_count +
+Return the total count of revisions for this item
+Author: Karl Goldstein @@ -194,18 +238,25 @@ See Also: content_revision.new - +
+- Function: -content_item.get_root_folder
+content_item.get_root_folder +
+Parameters: Not yet documented Declaration: function get_root_folder return cr_folders.folder_id%TYPE;
- -Function: content_item.get_template
Retrieves the template which should be used to render this item. +
+- +Function: content_item.get_template
Retrieves the template which should be used to render this item. If no template is registered to specifically render the item in the given context, the default template for the item's type is -returned.
+returned. +
+Author: Karl Goldstein @@ -228,11 +279,15 @@ -See Also: content_type.register_template, content_item.register_template, - -Function: content_item.get_title
Retrieves the title for the item, using either the latest or the +
+- +Function: content_item.get_title
Retrieves the title for the item, using either the latest or the live revision. If the specified item is in fact a folder, return the folder's label. In addition, this function will automatically -resolve symlinks.
+resolve symlinks. +
+Author: Karl Goldstein @@ -254,10 +309,14 @@ -See Also: content_item.get_live_revision, content_item.get_latest_revision, content_symlink.resolve - +
+- Function: -content_item.get_virtual_path
Retrieves the virtual path to an item, in the form of -"/tv/programs/star_trek/episode_203"
+content_item.get_virtual_path +
+Retrieves the virtual path to an item, in the form of +"/tv/programs/star_trek/episode_203"
+Author: Michael Pih @@ -279,11 +338,15 @@ -See Also: content_item.get_id, content_item.write_to_file, content_item.get_path - +
+- Function: -content_item.is_index_page
Determine if the item is an index page for the specified folder. +content_item.is_index_page +
Determine if the item is an index page for the specified folder. The item is an index page for the folder if it exists in the folder -and its item name is "index".
+and its item name is "index". +
+Author: Karl Goldstein @@ -304,13 +367,17 @@ See Also: content_folder.get_index_page - +
+- Function: -content_item.is_publishable
Determines if an item is publishable. Publishable items must +content_item.is_publishable +
Determines if an item is publishable. Publishable items must meet the following criteria: 1) for each child type, the item has n children, min_n < n < max_n 2) for each relation type, the item has n relations, min_n < n < max_n 3) any -'publishing_wf' workflows are finished
+'publishing_wf' workflows are finished +
+Author: Michael Pih @@ -324,9 +391,13 @@ ) return char; -- -Function: content_item.is_subclass
Determines if one type is a subclass of another. A class is -always a subclass of itself.
+
+
+- +Function: content_item.is_subclass
Determines if one type is a subclass of another. A class is +always a subclass of itself.
+Author: Karl Goldstein @@ -347,12 +418,16 @@ See Also: acs_object_type.create_type - +
+- Function: -content_item.is_valid_child
Determines if an item would be a valid child of another item by +content_item.is_valid_child +
Determines if an item would be a valid child of another item by checking if the parent allows children of the would-be child's content type and if the parent already has n_max children of that -content type.
+content type. +
+Author: Michael Pih @@ -371,10 +446,14 @@ ) return char; -- -Function: content_item.new
Creates a new content item. If the data, title +
+- +Function: content_item.new
Creates a new content item. If the data, title or text parameters are specified, also creates a revision -for the item.
+for the item. +
+Author: Karl Goldstein @@ -460,8 +539,11 @@ See Also: acs_object.new - -Function: content_item.relate
+
+
+- +Function: content_item.relate
Parameters: Not yet documented Declaration: function relate ( item_id in cr_items.item_id%TYPE, @@ -472,11 +554,15 @@ ) return cr_item_rels.rel_id%TYPE;
- -Procedure: content_item.copy
Copies the item to a new location, creating an identical item +
+- +Procedure: content_item.copy
Copies the item to a new location, creating an identical item with no revisions or associated workflow. If the target folder does not exist, or if the folder already contains an item with the same -name as the given item, an error will be thrown.
+name as the given item, an error will be thrown. +
+
+Author: Karl Goldstein Parameters: @@ -494,10 +580,14 @@
See Also: content_item.new, content_folder.new, content_item.move - -Procedure: content_item.delete
Deletes the specified content item, along with any revisions, +
+- +Procedure: content_item.delete
Deletes the specified content item, along with any revisions, symlinks, workflows, and template relations for the item. Use with -caution - this operation cannot be undone.
+caution - this operation cannot be undone. +
+Author: Karl Goldstein Parameters: @@ -510,10 +600,14 @@ See Also: acs_object.delete - -Procedure: content_item.move
Move the specified item to a different folder. If the target +
+- +Procedure: content_item.move
Move the specified item to a different folder. If the target folder does not exist, or if the folder already contains an item -with the same name as the given item, an error will be thrown.
+with the same name as the given item, an error will be thrown. +
+Author: Karl Goldstein Parameters: @@ -531,9 +625,13 @@
See Also: content_item.new, content_folder.new, content_item.copy - +
+- Procedure: -content_item.register_template
Registers a template which will be used to render this item.
+content_item.register_template +
Registers a template which will be used to render this item.
+Author: Karl Goldstein Parameters: @@ -556,9 +654,13 @@
See Also: content_type.register_template, content_item.unregister_template, content_item.get_template -- -Procedure: content_item.edit_name
Renames the item. If an item with the specified name already -exists under this item's parent, an error is thrown
+
+
+- +Procedure: content_item.edit_name
Renames the item. If an item with the specified name already +exists under this item's parent, an error is thrown
+
+Author: Karl Goldstein Parameters: @@ -576,9 +678,13 @@
See Also: content_item.new - +
+- Procedure: -content_item.set_live_revision
Make the specified revision the live revision for the item
+content_item.set_live_revision +
+Make the specified revision the live revision for the item
+
+Author: Karl Goldstein Parameters: @@ -593,11 +699,15 @@ See Also: content_item.get_live_revision - +
+- Procedure: -content_item.set_release_period
Sets the release period for the item. This information may be +content_item.set_release_period +
Sets the release period for the item. This information may be used by applications to update the publishing status of items at -periodic intervals.
+periodic intervals. +
+Author: Karl Goldstein Parameters: @@ -616,10 +726,14 @@ ); -
- +
+- Procedure: -content_item.unregister_template
Unregisters a template which will be used to render this -item.
+content_item.unregister_template +
+Unregisters a template which will be used to render this +item.
+
+Author: Karl Goldstein Parameters: @@ -642,9 +756,12 @@
See Also: content_type.register_template, content_item.register_template, content_item.get_template -- +
+- Procedure: -content_item.unset_live_revision
+content_item.unset_live_revision +
+Parameters: Not yet documented Declaration: procedure unset_live_revision ( --/** Set the live revision to null for the item @@ -655,10 +772,14 @@ );
- +
+- Procedure: -content_item.write_to_file
Writes the content of the live revision of this item to a file, -creating all the neccessary directories in the process
+content_item.write_to_file +
+Writes the content of the live revision of this item to a file, +creating all the neccessary directories in the process
+
+Author: Karl Goldstein Parameters: @@ -677,6 +798,7 @@
See Also: content_item.get_path
+
+ Last Modified: $Id$ - Index: openacs-4/packages/acs-content-repository/www/doc/api/keyword.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/api/keyword.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-content-repository/www/doc/api/keyword.adp 27 Oct 2014 16:39:14 -0000 1.2 +++ openacs-4/packages/acs-content-repository/www/doc/api/keyword.adp 25 Aug 2015 18:02:03 -0000 1.2.2.1 @@ -2,19 +2,30 @@{/doc/acs-content-repository {Content Repository}} {Package: content_keyword} Package: content_keyword - - - content_keyword
+
content_keyword
+Content Repository : -content_keyword
-
+content_keyword
+
+Overview
Keyword cassify a content_item. For example: If you have some +
+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
+to every single content_item. +
+Related Objects
+ See also: content_item -API
-
+
+API
+- Function: -content_keyword.get_description
Retrieves the description of the content keyword
+content_keyword.get_description +
+Retrieves the description of the content keyword
+Author: Karl Goldstein @@ -30,9 +41,13 @@ -See Also: content_keyword.get_heading, content_keyword.set_description - +
+- Function: -content_keyword.get_heading
Retrieves the heading of the content keyword
+content_keyword.get_heading +
+Retrieves the heading of the content keyword
+Author: Karl Goldstein @@ -48,9 +63,13 @@ -See Also: content_keyword.set_heading, content_keyword.get_description - -Function: content_keyword.get_path
Retreives a path to the keyword/subject category, with the most -general category at the root of the path
+
+
+- +Function: content_keyword.get_path
Retreives a path to the keyword/subject category, with the most +general category at the root of the path
+Author: Karl Goldstein @@ -66,9 +85,13 @@ See Also: content_keyword.new - +
+- Function: -content_keyword.is_assigned
Determines if the keyword is assigned to the item
+content_keyword.is_assigned +
+Determines if the keyword is assigned to the item
+Author: Karl Goldstein @@ -104,9 +127,13 @@ See Also: content_keyword.item_assign - -Function: content_keyword.is_leaf
Determines if the keyword has no sub-keywords associated with -it
+
+
+- +Function: content_keyword.is_leaf
Determines if the keyword has no sub-keywords associated with +it
+Author: Karl Goldstein @@ -122,8 +149,12 @@ See Also: content_keyword.new - -Function: content_keyword.new
Creates a new keyword (also known as "subject category").
+
+
+- +Function: content_keyword.new
Creates a new keyword (also known as "subject category").
+Author: Karl Goldstein @@ -170,10 +201,14 @@ -See Also: acs_object.new, content_item.new, content_keyword.item_assign, content_keyword.delete - -Procedure: content_keyword.delete
Deletes the specified keyword, which must be a leaf. Unassigns +
+- +Procedure: content_keyword.delete
Deletes the specified keyword, which must be a leaf. Unassigns the keyword from all content items. Use with caution - this -operation cannot be undone.
+operation cannot be undone. +
+
+Author: Karl Goldstein Parameters: @@ -186,10 +221,14 @@ See Also: acs_object.delete, content_keyword.item_unassign - +
+- Procedure: -content_keyword.item_assign
Assigns this keyword to a content item, creating a relationship -between them
+content_keyword.item_assign +
+Assigns this keyword to a content item, creating a relationship +between them
+
+Author: Karl Goldstein Parameters: @@ -216,10 +255,14 @@
See Also: acs_rel.new, content_keyword.item_unassign - +
+- Procedure: -content_keyword.item_unassign
Unassigns this keyword to a content item, removing a -relationship between them
+content_keyword.item_unassign +
Unassigns this keyword to a content item, removing a +relationship between them
+
+Author: Karl Goldstein Parameters: @@ -237,9 +280,13 @@
See Also: acs_rel.delete, content_keyword.item_assign - +
+- Procedure: -content_keyword.set_description
Sets a new description for the keyword
+content_keyword.set_description +
Sets a new description for the keyword
+
+Author: Karl Goldstein Parameters: @@ -258,9 +305,13 @@
See Also: content_keyword.set_heading, content_keyword.get_description -- +
+- Procedure: -content_keyword.set_heading
Sets a new heading for the keyword
+content_keyword.set_heading +
Sets a new heading for the keyword
+
+Author: Karl Goldstein Parameters: @@ -279,7 +330,8 @@
See Also: content_keyword.get_heading, content_keyword.set_description -
+
+ Last Modified: $Id: keyword.html,v 1.1.1.1 2001/03/13 22:59:26 ben Exp $ - Index: openacs-4/packages/acs-content-repository/www/doc/api/permission.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/api/permission.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-content-repository/www/doc/api/permission.adp 27 Oct 2014 16:39:14 -0000 1.2 +++ openacs-4/packages/acs-content-repository/www/doc/api/permission.adp 25 Aug 2015 18:02:03 -0000 1.2.2.1 @@ -2,22 +2,33 @@{/doc/acs-content-repository {Content Repository}} {Package: content_permission} Package: content_permission - - - content_permission
+
content_permission
+Content Repository : -content_permission
-
+content_permission
+
+Overview
Permissions can be set to allow certain users certain things. - +
+Overview
+Permissions can be set to allow certain users certain things. - They can be compared with the Unix filesystem permission: read, -write ...
Related Objects
+write ... +
+Related Objects
+ See also: {content_item } -API
-
+
+API
+- Function: -content_permission.has_grant_authority
Determine if the user may grant a certain permission to another +content_permission.has_grant_authority
Determine if the user may grant a certain permission to another user. The permission may only be granted if the user has the permission himself and posesses the cm_perm access, or if the user -posesses the cm_perm_admin access.
+posesses the cm_perm_admin access. +
+Author: Karl Goldstein @@ -43,13 +54,17 @@ content_permission.is_has_revoke_authority, acs_permission.grant_permission -- +
+- Function: -content_permission.has_revoke_authority
Determine if the user may take a certain permission away from +content_permission.has_revoke_authority +
Determine if the user may take a certain permission away from another user. The permission may only be revoked if the user has the permission himself and posesses the cm_perm access, while the other user does not, or if the user posesses the cm_perm_admin -access.
+access. +
+Author: Karl Goldstein @@ -78,12 +93,16 @@ content_permission.revoke_permission, acs_permission.revoke_permission -- +
+- Function: -content_permission.permission_p
Determine if the user has the specified permission on the +content_permission.permission_p +
Determine if the user has the specified permission on the specified object. Does NOT check objects recursively: that is, if the user has the permission on the parent object, he does not -automatically gain the permission on all the child objects.
+automatically gain the permission on all the child objects. +
+Author: Karl Goldstein @@ -109,12 +128,17 @@ content_permission.revoke_permission, acs_permission.permission_p -- +
+- Procedure: -content_permission.grant_permission
This is a helper function for +content_permission.grant_permission +
This is a helper function for content_permission.grant_permission and should not be called -individually.
Grants a permission and revokes all descendants of the -permission, since they are no longer relevant.
+individually. +
Grants a permission and revokes all descendants of the +permission, since they are no longer relevant.
+
+Author: Karl Goldstein Parameters: @@ -135,12 +159,17 @@
See Also: content_permission.grant_permission - +
+- Procedure: -content_permission.grant_permission_h
This is a helper function for +content_permission.grant_permission_h +
This is a helper function for content_permission.grant_permission and should not be called -individually.
Grants a permission and revokes all descendants of the -permission, since they are no longer relevant.
+individually. +
Grants a permission and revokes all descendants of the +permission, since they are no longer relevant.
+
+Author: Karl Goldstein Parameters: @@ -161,11 +190,15 @@
See Also: content_permission.grant_permission - +
+- Procedure: -content_permission.inherit_permissions
Make the child object inherit all of the permissions of the +content_permission.inherit_permissions +
Make the child object inherit all of the permissions of the parent object. Typically, this function is called whenever a new -object is created under a given parent
+object is created under a given parent +
+Author: Karl Goldstein Parameters: @@ -184,12 +217,17 @@
See Also: content_permission.grant, acs_permission.grant_permission - +
+- Procedure: -content_permission.revoke_permission
This is a helper function for +content_permission.revoke_permission +
This is a helper function for content_permission.revoke_permission and should not be called -individually.
Revokes a permission but grants all child permissions to the -holder, to ensure that the permission is not permanently lost
+individually. +
Revokes a permission but grants all child permissions to the +holder, to ensure that the permission is not permanently lost
+
+Author: Karl Goldstein Parameters: @@ -210,12 +248,17 @@
See Also: content_permission.revoke_permission - +
+- Procedure: -content_permission.revoke_permission_h
This is a helper function for +content_permission.revoke_permission_h +
This is a helper function for content_permission.revoke_permission and should not be called -individually.
Revokes a permission but grants all child permissions to the -holder, to ensure that the permission is not permanently lost
+individually. +
Revokes a permission but grants all child permissions to the +holder, to ensure that the permission is not permanently lost
+
+Author: Karl Goldstein Parameters: @@ -236,7 +279,8 @@
See Also: content_permission.revoke_permission
+
+ Last Modified: $Id: permission.html,v 1.1.1.1 2001/03/13 22:59:26 ben Exp $ - Index: openacs-4/packages/acs-content-repository/www/doc/api/revision.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/api/revision.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-content-repository/www/doc/api/revision.adp 27 Oct 2014 16:39:14 -0000 1.2 +++ openacs-4/packages/acs-content-repository/www/doc/api/revision.adp 25 Aug 2015 18:02:03 -0000 1.2.2.1 @@ -2,21 +2,32 @@{/doc/acs-content-repository {Content Repository}} {Package: content_revision} Package: content_revision - - - content_revision
+
content_revision
+Content Repository : -content_revision
-
+content_revision
+
+Overview
Content revisions contain the data for content items. There is a +
+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
+website at a given time. +
+Related Objects
+ See also: {content_item } -API
- -Function: content_revision.copy
Creates a new copy of an attribute, including all attributes
+
+API
+- +Function: content_revision.copy
Creates a new copy of an attribute, including all attributes
+
+Author: Karl Goldstein Parameters: @@ -30,20 +41,27 @@ See Also: content_revision.new - +
+- Function: -content_revision.export_xml
+content_revision.export_xml +
+Parameters: Not yet documented Declaration: function export_xml ( revision_id IN cr_revisions.revision_id%TYPE ) return cr_xml_docs.doc_id%TYPE;
- +
+- Function: -content_revision.get_number
Return the revision number of the specified revision, according +content_revision.get_number +
Return the revision number of the specified revision, according to the chronological order in which revisions have been added for -this item.
+this item. +
+Author: Karl Goldstein @@ -58,9 +76,12 @@ See Also: content_revision.new - +
+- Function: -content_revision.import_xml
+content_revision.import_xml +
+Parameters: Not yet documented Declaration: function import_xml ( item_id IN cr_items.item_id%TYPE, @@ -69,8 +90,12 @@ ) return cr_revisions.revision_id%TYPE;
- -Function: content_revision.new
Create a new revision for an item.
+
+
+- +Function: content_revision.new
Create a new revision for an item.
+Author: Karl Goldstein @@ -126,8 +151,11 @@ See Also: acs_object.new, content_item.new - -Function: content_revision.read_xml
+
+
+- +Function: content_revision.read_xml
Parameters: Not yet documented Declaration: function read_xml ( item_id IN number, @@ -141,9 +169,12 @@ ) return int';
- +
+- Function: -content_revision.write_xml
+content_revision.write_xml +
Parameters: Not yet documented Declaration: function write_xml ( revision_id IN number, @@ -156,8 +187,12 @@ ) return int';
- -Procedure: content_revision.delete
Deletes the revision.
+
+
+- +Procedure: content_revision.delete
Deletes the revision.
+
+Author: Karl Goldstein Parameters: @@ -170,11 +205,15 @@ See Also: content_revision.new, acs_object.delete - +
+- Procedure: -content_revision.index_attributes
Generates an XML document for insertion into +content_revision.index_attributes +
Generates an XML document for insertion into cr_revision_attributes, which is indexed by Intermedia for -searching attributes.
+searching attributes. +
+Author: Karl Goldstein Parameters: @@ -187,8 +226,11 @@ See Also: content_revision.new - -Procedure: content_revision.replace
+
+
+- +Procedure: content_revision.replace
Parameters: Not yet documented Declaration: procedure replace( revision_id number, search varchar2, replace varchar2) @@ -200,8 +242,12 @@ )';- -Procedure: content_revision.to_html
Converts a revision uploaded as a binary document to html
+
+
+- +Procedure: content_revision.to_html
Converts a revision uploaded as a binary document to html
+
+Author: Karl Goldstein Parameters: @@ -212,7 +258,8 @@ ); -
+
+ Last Modified: $Id: revision.html,v 1.1.1.1 2001/03/13 22:59:26 ben Exp $ - Index: openacs-4/packages/acs-content-repository/www/doc/api/symlink.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/api/symlink.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-content-repository/www/doc/api/symlink.adp 20 Aug 2015 17:19:49 -0000 1.2.2.1 +++ openacs-4/packages/acs-content-repository/www/doc/api/symlink.adp 25 Aug 2015 18:02:03 -0000 1.2.2.2 @@ -2,18 +2,29 @@{/doc/acs-content-repository {Content Repository}} {Package: content_symlink} Package: content_symlink - - - content_symlink
+
content_symlink
+Content Repository : -content_symlink
-
+content_symlink
+
+Overview
Symlinks are pointers to items within the content repository. -They are simply used to create links between content items.
Related Objects
+
+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
-
+
+API
+- Function: -content_symlink.is_symlink
Determines if the item is a symlink
+content_symlink.is_symlink +
+Determines if the item is a symlink
+Author: Karl Goldstein @@ -28,8 +39,12 @@ See Also: content_symlink.new, content_symlink.resolve - -Function: content_symlink.new
Create a new symlink, linking two items
+
+
+- +Function: content_symlink.new
Create a new symlink, linking two items
+Author: Karl Goldstein @@ -76,8 +91,12 @@ See Also: acs_object.new, content_item.new, content_symlink.resolve - -Function: content_symlink.resolve
Resolves the symlink and returns the target item id.
+
+
+- +Function: content_symlink.resolve
Resolves the symlink and returns the target item id.
+Author: Karl Goldstein @@ -93,9 +112,13 @@ See Also: content_symlink.new, content_symlink.is_symlink - +
+- Function: -content_symlink.resolve_content_type
Gets the content type of the target item.
+content_symlink.resolve_content_type +
Gets the content type of the target item.
+Author: Michael Pih @@ -111,9 +134,13 @@ See Also: content_symlink.resolve - -Procedure: content_symlink.copy
Copies the symlink itself to another folder, without resolving -the symlink
+
+
+- +Procedure: content_symlink.copy
Copies the symlink itself to another folder, without resolving +the symlink
+Author: Karl Goldstein Parameters: @@ -131,8 +158,12 @@
See Also: content_symlink.new, content_item.copy - -Procedure: content_symlink.delete
Deletes the symlink
+
+
+- +Procedure: content_symlink.delete
Deletes the symlink
+
+Author: Karl Goldstein Parameters: @@ -145,7 +176,8 @@ See Also: content_symlink.new, acs_object.delete
+
+ Last Modified: $Id: symlink.html,v 1.2 2014/10/27 16:39:14 victorg Exp $ - Index: openacs-4/packages/acs-content-repository/www/doc/api/template.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/api/template.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-content-repository/www/doc/api/template.adp 27 Oct 2014 16:39:14 -0000 1.2 +++ openacs-4/packages/acs-content-repository/www/doc/api/template.adp 25 Aug 2015 18:02:03 -0000 1.2.2.1 @@ -2,21 +2,32 @@{/doc/acs-content-repository {Content Repository}} {Package: content_template} Package: content_template - - - content_template
+
content_template
+Content Repository : -content_template
-
+content_template
+
+Overview
Templates are a special class of text objects that are used for +
+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
+mapping to a template itself. +
+Related Objects
+ See also: content_item, content_folder -API
- -Function: content_template.get_path
Retrieves the full path to the template, as described in -content_item.get_path
+
+
+API
+- +Function: content_template.get_path
Retrieves the full path to the template, as described in +content_item.get_path
+Author: Karl Goldstein @@ -38,16 +49,23 @@ See Also: content_item.get_path - +
+- Function: -content_template.get_root_folder
+content_template.get_root_folder +
+Parameters: Not yet documented Declaration: function get_root_folder return cr_folders.folder_id%TYPE;
- +
+- Function: -content_template.is_template
Determine if an item is a template.
+content_template.is_template +
+Determine if an item is a template.
+Author: Karl Goldstein @@ -62,9 +80,13 @@ See Also: content_template.new - -Function: content_template.new
Creates a new content template which can be used to render -content items.
+
+
+- +Function: content_template.new
Creates a new content template which can be used to render +content items.
+Author: Karl Goldstein @@ -105,10 +127,14 @@ -See Also: acs_object.new, content_item.new, content_item.register_template, content_type.register_template - -Procedure: content_template.delete
Deletes the specified template, and unregisters the template +
+- +Procedure: content_template.delete
Deletes the specified template, and unregisters the template from all content types and content items. Use with caution - this -operation cannot be undone.
+operation cannot be undone. +
+Author: Karl Goldstein Parameters: @@ -122,7 +148,8 @@ -See Also: acs_object.delete, content_item.unregister_template, content_type.unregister_template,
+
+ Last Modified: $Id: template.html,v 1.1.1.1 2001/03/13 22:59:26 ben Exp $ - Index: openacs-4/packages/acs-content-repository/www/doc/api/type.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/api/type.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-content-repository/www/doc/api/type.adp 27 Oct 2014 16:39:14 -0000 1.2 +++ openacs-4/packages/acs-content-repository/www/doc/api/type.adp 25 Aug 2015 18:02:04 -0000 1.2.2.1 @@ -2,21 +2,32 @@{/doc/acs-content-repository {Content Repository}} {Package: content_type} Package: content_type - - - content_type
+
content_type
+Content Repository : -content_type
-
+content_type
+
+Overview
This package is used to manipulate content types and attributes +
+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
+a website. All content items should subclass a content type. +
+Related Objects
+ See also: {Content Item } -API
-
+
+API
+- Function: -content_type.create_attribute
Create a new attribute for the specified type. Automatically +content_type.create_attribute
Create a new attribute for the specified type. Automatically create the column for the attribute if the column does not already -exist.
+exist. +
+Author: Karl Goldstein @@ -47,9 +58,13 @@ See Also: acs_object_type.create_attribute, content_type.create_type - -Function: content_type.get_template
Retrieve the appropriate template for rendering items of the -specified type.
+
+
+- +Function: content_type.get_template
Retrieve the appropriate template for rendering items of the +specified type.
+Author: Karl Goldstein @@ -73,18 +88,25 @@ content_type.unregister_template, content_type.register_template, content_type.set_default_template -- +
+- Function: -content_type.is_content_type
+content_type.is_content_type +
Parameters: Not yet documented Declaration: function is_content_type ( object_type in acs_object_types.object_type%TYPE ) return char;
- -Procedure: content_type.create_type
Create a new content type. Automatically create the attribute -table for the type if the table does not already exist.
+
+
+- +Procedure: content_type.create_type
Create a new content type. Automatically create the attribute +table for the type if the table does not already exist.
+
+Author: Karl Goldstein Parameters: @@ -120,11 +142,15 @@
See Also: acs_object_type.create_type - +
+- Procedure: -content_type.drop_attribute
Drop an existing attribute. If you are using CMS, make sure to +content_type.drop_attribute +
Drop an existing attribute. If you are using CMS, make sure to call cm_form_widget.unregister_attribute_widget before -calling this function.
+calling this function. +
+
+Author: Karl Goldstein Parameters: @@ -148,10 +174,14 @@
See Also: acs_object.drop_attribute, content_type.create_attribute, cm_form_widget.unregister_attribute_widget -- +
+- Procedure: -content_type.refresh_view
Create a view for the type which joins all attributes of the +content_type.refresh_view +
Create a view for the type which joins all attributes of the type, including the inherited attributes. The view is named "
+ X" Called by create_attribute and create_type.@@ -166,12 +196,16 @@ See Also: content_type.create_type - +
+- Procedure: -content_type.register_child_type
Register a parent-child relationship between a content type and +content_type.register_child_type +
Register a parent-child relationship between a content type and another object type. This may then be used by the content_item.is_valid_relation function to validate the -relationship between an item and a potential child.
+relationship between an item and a potential child. +
+Author: Karl Goldstein Parameters: @@ -202,22 +236,29 @@
See Also: content_type.register_relation_type, content_type.register_child_type -- +
+- Procedure: -content_type.register_mime_type
+content_type.register_mime_type +
+Parameters: Not yet documented Declaration: procedure register_mime_type ( content_type in cr_content_mime_type_map.content_type%TYPE, mime_type in cr_content_mime_type_map.mime_type%TYPE );
- +
+- Procedure: -content_type.register_relation_type
Register a relationship between a content type and another +content_type.register_relation_type +
Register a relationship between a content type and another object type. This may then be used by the content_item.is_valid_relation function to validate any -relationship between an item and another object.
+relationship between an item and another object. +
+Author: Karl Goldstein Parameters: @@ -248,10 +289,14 @@
See Also: content_type.unregister_relation_type - +
+- Procedure: -content_type.register_template
Register a template for the content type. This template may be -used to render all items of that type.
+content_type.register_template +
Register a template for the content type. This template may be +used to render all items of that type.
+
+Author: Karl Goldstein Parameters: @@ -280,11 +325,15 @@ content_type.unregister_template, content_type.set_default_template, content_type.get_template -
- +
+- Procedure: -content_type.set_default_template
Make the registered template a default template. The default +content_type.set_default_template +
Make the registered template a default template. The default template will be used to render all items of the type for which no -individual template is registered.
+individual template is registered. +
+Author: Karl Goldstein Parameters: @@ -309,12 +358,16 @@ content_type.unregister_template, content_type.register_template, content_type.get_template -
- +
+- Procedure: -content_type.unregister_child_type
Register a parent-child relationship between a content type and +content_type.unregister_child_type +
Register a parent-child relationship between a content type and another object type. This may then be used by the content_item.is_valid_relation function to validate the -relationship between an item and a potential child.
+relationship between an item and a potential child. +
+Author: Karl Goldstein Parameters: @@ -336,20 +389,27 @@
See Also: content_type.register_relation_type, content_type.register_child_type -- +
+- Procedure: -content_type.unregister_mime_type
+content_type.unregister_mime_type +
+Parameters: Not yet documented Declaration: procedure unregister_mime_type ( content_type in cr_content_mime_type_map.content_type%TYPE, mime_type in cr_content_mime_type_map.mime_type%TYPE );
- +
+- Procedure: -content_type.unregister_relation_type
Unregister a relationship between a content type and another -object type.
+content_type.unregister_relation_type +
Unregister a relationship between a content type and another +object type.
+
+Author: Karl Goldstein Parameters: @@ -372,11 +432,15 @@
See Also: content_type.register_relation_type - +
+- Procedure: -content_type.unregister_template
Unregister a template. If the unregistered template was the +content_type.unregister_template +
Unregister a template. If the unregistered template was the default template, the content_type can no longer be rendered in the -use_context,
+use_context, +
+
+Author: Karl Goldstein Parameters: @@ -400,7 +464,8 @@ content_type.set_default_template, content_type.register_template, content_type.get_template -
+
+ Last Modified: $Id: type.html,v 1.1.1.1 2001/03/13 22:59:26 ben Exp $ - Index: openacs-4/packages/acs-content-repository/www/doc/guide/access-control.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/guide/access-control.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-content-repository/www/doc/guide/access-control.adp 27 Oct 2014 16:39:15 -0000 1.2 +++ openacs-4/packages/acs-content-repository/www/doc/guide/access-control.adp 25 Aug 2015 18:02:04 -0000 1.2.2.1 @@ -2,6 +2,5 @@{/doc/acs-content-repository {Content Repository}} {} - - Last Modified: $Id: access-control.html,v 1.1.1.1 2001/03/13 -22:59:26 ben Exp $
+Last Modified: $Id: access-control.html,v 1.1.1.1 2001/03/13 +22:59:26 ben Exp $
Index: openacs-4/packages/acs-content-repository/www/doc/guide/convert.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/guide/convert.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-content-repository/www/doc/guide/convert.adp 20 Aug 2015 17:19:49 -0000 1.2.2.1 +++ openacs-4/packages/acs-content-repository/www/doc/guide/convert.adp 25 Aug 2015 18:02:04 -0000 1.2.2.2 @@ -2,39 +2,51 @@{/doc/acs-content-repository {Content Repository}} {Content Repository Developer Guide: HTML Conversion} Content Repository Developer Guide: HTML Conversion - - - Converting Binary Documents to HTML
The content repository uses the INSO libraries included with +
Converting Binary Documents to HTML
+The content repository uses the INSO libraries included with Intermedia to support conversion of binary files such as Microsoft Word documents to HTML. This document describes how to make this conversion be part of the item creation or editing process, such -that the content is always stored in the repository as HTML.
+that the content is always stored in the repository as HTML.
+Note: Because temporary tables and LOB storage are used during the conversion process, the entire process described here -must be performed within the context of a single transaction.
Create the Revision
The first step is to create the revision that will be associated +must be performed within the context of a single transaction.
+Create the Revision
+The first step is to create the revision that will be associated with the converted document, and obtain the corresponding ID. The content column for the revision must be initialized with -an empty blob object:
+an empty blob object: +
+revision_id := content_revision.new(item_id => :item_id, revision_id => :revision_id, data => empty_blob(), title => 'My Word Document', ...); -Uploading Binary Files
The next step in the process is to upload the binary file into +
Uploading Binary Files
+The next step in the process is to upload the binary file into the temporary table cr_doc_filter. This may be done using any standard technique for uploading a binary file, such as an image. The temporary table has only two columns; one is a BLOB to -store the document itself, and one is the revision ID.
Converting the Document
Once the revision has been created and the file has been +store the document itself, and one is the revision ID.
+Converting the Document
+Once the revision has been created and the file has been uploaded, the file may be converted to HTML and written into the empty blob associated with the revision. This is done with the to_html procedure in the content_revision -package:
+package: +
+begin content_revision.to_html(:revision_id); end; / -
Once the transaction is committed, the uploaded document is -automatically deleted from the cr_doc_filter table.
karlg\@arsdigita.com
+Once the transaction is committed, the uploaded document is +automatically deleted from the cr_doc_filter table.
+
+karlg\@arsdigita.com +
+ Last Modified: $Id: convert.html,v 1.1.1.1 2001/03/13 22:59:26 ben Exp $ - Index: openacs-4/packages/acs-content-repository/www/doc/guide/file-system.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/guide/file-system.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-content-repository/www/doc/guide/file-system.adp 20 Aug 2015 17:19:49 -0000 1.2.2.1 +++ openacs-4/packages/acs-content-repository/www/doc/guide/file-system.adp 25 Aug 2015 18:02:04 -0000 1.2.2.2 @@ -4,34 +4,41 @@Content Repository Developer Guide: Organizing Content Items - - - Organizing Content Items
The content repository organizes content items in a hierarchical +
Organizing Content Items
+The content repository organizes content items in a hierarchical structure similar to a file system. You manage content items in the -repository using the same basic operations as in a file system:
-
+repository using the same basic operations as in a file system:
+
- A freshly installed content repository consists of a single "root" folder (analogous to the root directory / in UNIX or an empty partition in Windows or MacOS).
- You organize items by creating subfolders under the root.
- You can move or copy items from one folder to another.
- You can create "links" or "shortcuts" for items to make them accessible from within other directories.
- Each item has a "file name" and an absolute "path" that is determined by its location on a particular branch of the repository tree. For example, the path to an item named widget in the folder products would be /products/widget. -
The content repository adds an additional twist to a traditional +
The content repository adds an additional twist to a traditional filesystem: any content item, not just a folder, may serve as a container for any number of other content items. For example, imagine a book consisting of a preface, a number of chapters and a bibliography (which in turn may have any number of entries). The book itself is a content item, in that it has attributes (publisher, ISBN number, publication date, synopsis, etc.) associated with it. It also is the logical container for all its -components.
It is important to note that folders are simply a special +components.
+It is important to note that folders are simply a special subtype of content item. The content repository's representation of a parent-child relationship between a folder and the items it contains is no different from the relationship between a book and its chapters. Folders may be thought of simply as generic containers for grouping items that are not necessarily part of a -greater whole.
An Example
Consider a simple repository structure with the following -contents:
Note the following:
-
+greater whole.
+
- The root folder of the content repository has a special ID which is returned by the function content_item.get_root_folder.
- Regular content items such as index and about @@ -41,28 +48,34 @@ item_id of the "About Us" page.
- The "Press" folder contains two items. Internally, the parent_id of the "Press Index" and "Release One" items are set to the item_id of the "Press" folder. -
An Example
+Consider a simple repository structure with the following +contents:
+
+Note the following:
+Note that the same effective organization could have been +
Note that the same effective organization could have been achieved by creating the "Press Index" item under the root, and having press releases as its children. Using the folder approach -may have the following advantages:
-
+may have the following advantages:
+
- Content management systems can take advantage of the folder structure to implement an intuitive user interface analagous to familiar desktop tools (Windows Explorer, MacOS Finder, etc.).
- You can use the content repository API to constraint the type of content that a folder may contain (except for the index page). For example, it is possible to limit the contents of the "Press" folder to items of type "Press Release." See the Content Folder API for more details. -
Using your own root
By default, the content repository has one root folder for +
Using your own root
+By default, the content repository has one root folder for content items and one for templates. In some situations, that is not enough. For example, a package that can be instantiated several times might wish to store the content for each instance in its own content root. Creating your own content (and template) root also has the advantage that you will not accidentally access another package's content nor will another package access your content. Not that that could do any harm, because you have secured all your -content through appropriate permissions.
We only talk about creating content roots from here on — +content through appropriate permissions.
+We only talk about creating content roots from here on — creating template roots is completely analogous. You create your own content root by calling content_folder.new in -PL/SQL:
+PL/SQL: +
+declare v_my_content_root integer; begin @@ -74,20 +87,26 @@ -- Store v_my_content_root in a safe place end; / -
The important point is that you have to pass in 0 for +
The important point is that you have to pass in 0 for the parent_id. This parent_id is special in that -it indicates folders with no parent.
The content repository does not keep track of who created what +it indicates folders with no parent.
+The content repository does not keep track of who created what root folders. You have to do that yourself. In the above example, you need to store the value v_my_content_root somewhere, for example a table that is specific for your package, otherwise you won't have a reliable way of accessing your new content -root.
With multiple content roots, there can be many items with +root.
+With multiple content roots, there can be many items with item_path'/news/article' and you need to tell the content repository which root you are talking about. For example, to retrieve content through content_item.get_id, you pass the id of your content root as the root_folder_id parameter to specify the content root under which the -item_path should be resolved.
karlg\@arsdigita.com
+item_path should be resolved. +
+karlg\@arsdigita.com +
+ Last Modified: $Id: file-system.html,v 1.1.1.1 2001/03/13 22:59:26 ben Exp $ - Index: openacs-4/packages/acs-content-repository/www/doc/guide/items.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/guide/items.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-content-repository/www/doc/guide/items.adp 20 Aug 2015 17:19:50 -0000 1.2.2.1 +++ openacs-4/packages/acs-content-repository/www/doc/guide/items.adp 25 Aug 2015 18:02:04 -0000 1.2.2.2 @@ -4,25 +4,31 @@Content Repository Developer Guide: Creating Content Items - - - Creating Content Items
Use the Content Item API to create the item
Content items are initialized using the +
Creating Content Items
+Use the Content Item API to create the item
+Content items are initialized using the content_item.new function. A name is the only parameter -required to create an item:
+required to create an item: +
+item_id := content_item.new( name => 'my_item' ); -
The name represents the tail of the URL for that content item. +
The name represents the tail of the URL for that content item. In most cases you will want to create items in a particular context -with the repository hierarchy:
+with the repository hierarchy: +
+item_id := content_item.new( name => 'my_item', parent_id => :parent_id ); -The parent ID must be another content item, or a subclass of -content item such as a folder.
The content_item.new function accepts a number of other +
The parent ID must be another content item, or a subclass of +content item such as a folder.
+The content_item.new function accepts a number of other optional parameters. The standard creation_date, creation_user and creation_ip should be specified for auditing purposes. You can also create the initial revision and -publish text items in a single step:
+publish text items in a single step: +
+item_id := content_item.new( name => 'my_item', parent_id => :parent_id, @@ -31,14 +37,20 @@ Here comes a car...uh oh! The End', is_live => 't' ); -If either the title or text are not null, the function will +
If either the title or text are not null, the function will create the first revision of the item. It will also mark the item as live if the is_live parameter is true. The alternative to this one step method is to create a content item and then add a -revision using the Content Revision API.
Publishing a content item
If a content item has at least one revision, then it can be +revision using the Content Revision API.
+Publishing a content item
+If a content item has at least one revision, then it can be published by calling the content_item.set_live_revision -procedure, which takes as input a revision_id:
+procedure, which takes as input a revision_id: +
+content_item.set_live_revision( revision_id => :revision_id ); -
karlg\@arsdigita.comLast Modified: $Id: items.html,v 1.1.1.1 2001/03/13 22:59:26 ben +
+karlg\@arsdigita.com +Last Modified: $Id: items.html,v 1.1.1.1 2001/03/13 22:59:26 ben Exp $
- Index: openacs-4/packages/acs-content-repository/www/doc/guide/keywords.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/guide/keywords.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-content-repository/www/doc/guide/keywords.adp 27 Oct 2014 16:39:15 -0000 1.2 +++ openacs-4/packages/acs-content-repository/www/doc/guide/keywords.adp 25 Aug 2015 18:02:04 -0000 1.2.2.1 @@ -4,9 +4,10 @@Content Repository Developer Guide: Subject Keywords (Categories) - - - Subject Keywords (Categories)
Overview
+
Subject Keywords (Categories)
+
+Overview
+Subject Keywords are used to implement categorization for the Content Management system. A Subject Keyword is a small label, such as "Oracle Documentation" or "My Favorite Foods", which @@ -16,22 +17,29 @@ items "Potstickers", "Strawberries" and "Ice Cream" would indicate that all the three items belong in the same category - namely, the category of the user's favorite foods. The actual physical location -of these items within the repository is irrelevant.
Subject Keywords may be nested to provide more detailed control +of these items within the repository is irrelevant.
+Subject Keywords may be nested to provide more detailed control over categorization; for example, "My Favorite Foods" may be further subdivided into "Healthy" and "Unhealthy". Subject Keywords which have descendants are referred to as "Subject -Categories".
Data Model
The content_keyword object type is used to represent +Categories".
+Data Model
+The content_keyword object type is used to represent Subject Keywords (see content_keyword.sql) The content_keyword type inherits from -acs_object:
+acs_object: +
+acs_object_type.create_type ( supertype => 'acs_object', object_type => 'content_keyword', pretty_name => 'Content Keyword', pretty_plural => 'Content Keywords', table_name => 'cr_keywords', id_column => 'keyword_id', name_method => 'acs_object.default_name' );-In addition, the cr_keywords table (see -content-create.sql) contains extended attributes of + +In addition, the cr_keywords + table (see +content-create.sql +) contains extended attributes of Subject Keywords:create table cr_keywords ( @@ -44,7 +52,9 @@ description varchar2(4000) );
-In content-keyword.sql: + +In content-keyword.sql +:attr_id := acs_attribute.create_attribute ( object_type => 'acs_object', @@ -61,11 +71,14 @@ pretty_name => 'Description', pretty_plural => 'Descriptions' ); -
Thus, each Subject Keyword has a heading, which is a +
Thus, each Subject Keyword has a heading, which is a user-readable heading for the keyword, and a description, -which is a somewhat longer description of the keyword.
The cr_item_keyword_map table (see +which is a somewhat longer description of the keyword.
+The cr_item_keyword_map table (see content-create.sql) is used to relate content items to -keywords:
+keywords: +
+create table cr_item_keyword_map ( item_id integer constraint cr_item_keyword_map_item_fk @@ -80,10 +93,13 @@ constraint cr_item_keyword_map_pk primary key (item_id, keyword_id) ); --API Access
The API used to access and modify content keywords are outlined +
+API Access
+The API used to access and modify content keywords are outlined below. The function names are links that will take you to a more -detailed description of the function and its parameters.
+detailed description of the function and its parameters. +
- Index: openacs-4/packages/acs-content-repository/www/doc/guide/object-relationships.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/guide/object-relationships.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-content-repository/www/doc/guide/object-relationships.adp 20 Aug 2015 17:19:50 -0000 1.2.2.1 +++ openacs-4/packages/acs-content-repository/www/doc/guide/object-relationships.adp 25 Aug 2015 18:02:04 -0000 1.2.2.2 @@ -4,38 +4,45 @@Function/Procedure Purpose Description @@ -127,4 +143,3 @@ Content Repository Developer Guide: Object Relationships - - - Object Relationships
Many applications of the content repository require that content +
Object Relationships
+Many applications of the content repository require that content items be related to each other as well as to other classes of -objects. Examples include:
-
+objects. Examples include:
+
- News stories may be linked to other stories on the same topic.
- An article may be linked to any number of photos or charts that are embedded in the article.
- A long article is divided into multiple sections, each of which is intended for separate display.
- Product reviews are linked to specific products.
- User portraits are linked to specific users. -
The ACS kernel provides a standard, highly flexible data model +
The ACS kernel provides a standard, highly flexible data model and API for relating objects to other objects. If you have a highly specific problem and are developing your own user interface on the content repository, you can use the ACS relationships framework directly. The relationship framework in the content repository itself is simply intended as a convenience for handling common -relationship situations involving content items.
Parent-Child Relationships
In many cases one content item may serve as a natural container +relationship situations involving content items.
+Parent-Child Relationships
+In many cases one content item may serve as a natural container for another item. An article divided into sections, or a news story with an associated photo are one example of this. These "parent-child" relationships are handled by the basic hierarchical organization of the content repository. Every item has a parent item, represented internally by the parent_id column in -the cr_items table.
It is often desirable to constrain the number and content type +the cr_items table.
+It is often desirable to constrain the number and content type of child items. For example, the specifications for a news story may only allow for a single photo. A structured report may have exactly three sections. Furthermore, it may be necessary to classify or identify child items of the same type. Clearly the sections of a report would have a logical order in which they would need to be presented to the user. The layout for a photo album may -have a special position for a "featured" photo.
++have a special position for a "featured" photo. + 
The content repository accomodates these situations in the -following ways:
-
+
The content repository accomodates these situations in the +following ways:
+- An API procedure, content_type.register_child_type, may be used to specify the minimum and maximum number of children of a particular content type that an item may have. You may @@ -53,17 +60,22 @@ relationships are themselves treated as ACS Objects, so this table may be extended with additional attributes as required by the developer. -
Note that there is no currently no explicit API to "add a + +
Note that there is no currently no explicit API to "add a child." You specify the parent of an item upon creating it. You can use the API procedure content_item.move to change the -parent of an item.
Item-Object Relationships
In addition to the relationships to their parents and children +parent of an item.
+Item-Object Relationships
+In addition to the relationships to their parents and children in the content repository hierarchy, content items may be linked to any number of other objects in the system. This may include -products, users or content items on related subjects.
The same need to constrain the possibilities for an item-object +products, users or content items on related subjects.
+The same need to constrain the possibilities for an item-object relationship, as described above for parents and children, also apply to items and objects in general. The content repository provides a data model and API for managing these constraints that -parallels what is provided for parent-child relationships:
-
+parallels what is provided for parent-child relationships:
+
- An API procedure, content_type.register_relation_type, may be used to specify the minimum and maximum number of relations with a particular object type that an item may have. There is no @@ -83,11 +95,16 @@ relationships are themselves treated as ACS Objects, so this table may be extended with additional attributes as required by the developer. -
Extending Parent-Child and Item-Object Relationships
The simple relation mechanisms described above may not be +
Extending Parent-Child and Item-Object Relationships
+The simple relation mechanisms described above may not be sufficient for some applications. However, because both relationships defined by the content repository are themselves objects, you have the option to extend their -types as you would for any other ACS object.
karlg\@arsdigita.com
+types as you would for any other ACS object. +
+karlg\@arsdigita.com +
+ Last modified: $Id: object-relationships.html,v 1.1.1.1 2001/03/13 22:59:26 ben Exp $ - Index: openacs-4/packages/acs-content-repository/www/doc/guide/publish.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/guide/publish.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-content-repository/www/doc/guide/publish.adp 20 Aug 2015 17:19:50 -0000 1.2.2.1 +++ openacs-4/packages/acs-content-repository/www/doc/guide/publish.adp 25 Aug 2015 18:02:04 -0000 1.2.2.2 @@ -4,25 +4,31 @@Content Repository Developer Guide: Publishing Content - - - Publishing Content
The content repository does not place any restrictions on the +
Publishing Content
+The content repository does not place any restrictions on the methods employed for delivering content via a public server infrastructure. Applications are free to query the repository and -process the data in any way desired.
Although there are no restrictions on publishing methodology, +process the data in any way desired.
+Although there are no restrictions on publishing methodology, the repository API is intended to facilitate generic template-based publication, regardless of the specific presentation layer used. The following diagram illustrates the steps typically involved in -such a publication process:
In general, there is an initial resolution step in +such a publication process:
+
+In general, there is an initial resolution step in which the server must identify the appropriate content item and then decide which template to actually parse. Following that is an execution step, during which setup tasks associated with the template are performed. Finally, the merging step -combines the data and layout into a rendered page.
Matching URLs to Content Items
The primary mechanism for matching URLs to Content Items are +combines the data and layout into a rendered page.
+Matching URLs to Content Items
+The primary mechanism for matching URLs to Content Items are virtual URL handlers, .vuh files. An explanation of virtual URL handlers can be found in the tutorial on the -Request Processor.
Here is an example index.vuh file that you can adapt to -your own purposes:
+Request Processor. +
+Here is an example index.vuh file that you can adapt to +your own purposes:
+# Get the paths set the_url [ad_conn path_info] @@ -44,14 +50,17 @@ } else { ns_returnnotfound } -The content_root and template_root parameters +
The content_root and template_root parameters select the content and template root folders. In the example, they are just the default roots that the content repository initializes on installation. If you want to store your content completely independent from that of other packages, you can initialize your own content root and pass that folder's ID on to -content::init.
To publish content through URLs that are underneath -/mycontent you need to do the following:
-
+content::init.
+
- Create a directory mycontent in your server's page root and an index.vuh file in that directory.
- Adapt the set content_root ... and set template_root .. statements in the example above so that they @@ -60,11 +69,16 @@ variable the_url contains the absolute path to the content item you wish to serve from your (or the default) content root. -
To publish content through URLs that are underneath +/mycontent you need to do the following:
+If you use the example index.vuh file above unaltered +
If you use the example index.vuh file above unaltered for requests to my_content, a request for http://yourserver/mycontent/news/articles/42 would request the content item /news/articles/42 from the content -repository on the default content root folder.
Matching Content Items to Templates
Querying Content
Querying Attributes
When you create a new content type or add an attribute to an +repository on the default content root folder.
+Matching Content Items to Templates
+Querying Content
+Querying Attributes
+When you create a new content type or add an attribute to an existing content type, a view is created (or recreated) that joins the attribute tables for the entire chain of inheritance for that content type. The view always has the same name as the attribute @@ -73,24 +87,34 @@ Press Releases is press_releases, then the view will be named press_releasesx. Querying this view is a convenient means of accessing any attribute associated with a -content item.
As a shortcut, the item's template may call +content item.
+As a shortcut, the item's template may call content::get_content in its Tcl file in order to automatically retrieve the current item's attributes. The attributes will be placed in a onerow datasource called content . The template may then call template::util::array_to_vars content in order to convert -the onerow datasource to local variables.
In addition to the "x" view, the Content Repository creates an +the onerow datasource to local variables.
+In addition to the "x" view, the Content Repository creates an "i" view, which simplifies the creation of new revisions. The "i" view has the same name as the content table, with "i" appended at the end. You may insert into the view as if it was a normal table; the insert trigger on the view takes care of inserting the actual -values into the content tables.
Querying Additional Data
Templates often display more than simple content attributes. +values into the content tables.
+Querying Additional Data
+Templates often display more than simple content attributes. Additional queries may be necessary to obtain data about related objects not described directly in attribute tables. The setup code associated with a template typically performs these queries after -the initial query for any needed attributes.
Merging Data with Templates
Returning Output
-
+the initial query for any needed attributes.
+
- Write to the file system
- Service public requests directly -
Merging Data with Templates
+Returning Output
+
karlg\@arsdigita.com
+
+karlg\@arsdigita.com +
+ Last Modified: $Id: publish.html,v 1.4 2013/04/12 16:12:56 gustafn Exp $ - Index: openacs-4/packages/acs-content-repository/www/doc/guide/revisions.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/guide/revisions.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-content-repository/www/doc/guide/revisions.adp 20 Aug 2015 17:19:50 -0000 1.2.2.1 +++ openacs-4/packages/acs-content-repository/www/doc/guide/revisions.adp 25 Aug 2015 18:02:05 -0000 1.2.2.2 @@ -4,10 +4,10 @@Content Repository Developer Guide: Creating Content Revisions - - - Creating Content Revisions
At a basic level, creating a new revision of a content item -involves the following steps:
-
+
- Insert a row in the acs_objects table to create the object.
- Insert a corresponding row in the cr_revisions table with the basic attributes for the revision.
- Write the content data into the content BLOB column of @@ -17,24 +17,30 @@ thereof.
- Insert a corresponding row into the attribute table of the content type of the item. This is not applicable if the content type is Basic Item. -
Creating Content Revisions
+At a basic level, creating a new revision of a content item +involves the following steps:
+Use the Content Revision API to create a revision
Content revisions are initialized using the +
Use the Content Revision API to create a revision
+Content revisions are initialized using the content_revision.new function. The only parameters required to create the revision are a title, a content item ID, and -some text:
+some text: +
+revision_id := content_revision.new( title => 'A Revision', item_id => :item_id, text => 'Once upon a time Goldilocks crossed the street. Here comes a car...uh oh! The End' ); -The item_id parameter is ID of the content item with -which the revision is associated.
The content_item.new function accepts a number of other +
The item_id parameter is ID of the content item with +which the revision is associated.
+The content_item.new function accepts a number of other optional parameters: description, mime_type, and publish_date. The standard creation_date, creation_user, and creation_ip should be specified for auditing purposes. Instead of the text parameter, this function can be called with a data -parameter, in which data is a blob:
+parameter, in which data is a blob: +
+revision_id := content_revision.new( title => 'A Revision', description => 'A Description of a revision', @@ -46,17 +52,21 @@ creation_user => :user_id, creation_ip => :ip_address ); -Insert additional attributes
Given that there is no way (AFAIK) to pass variable parameters +
Insert additional attributes
+Given that there is no way (AFAIK) to pass variable parameters to a PL/SQL function, there is no way to make content_revision.new generic enough to support submission of the attributes for all different content types. This leaves you -with three alternatives:
-
+with three alternatives:
+
- Call content_revision.new followed by manual DML statements to write data into the content BLOB and insert attributes.
- Write a PL/SQL package for each of your content types, which encapsulates the above code.
- Create revisions by inserting into the attribute view for each content type. -
The last option is made possible by an instead of +
The last option is made possible by an instead of insert trigger on the attribute view for each content type. (An attribute view joins together the storage tables for the ancestors of each content type, including acs_objects @@ -68,32 +78,44 @@ and executed with each call to content_type.create_attribute. The trigger makes it possible to create complete revisions with a single insert -statement:
+statement: +
+insert into cr_revisionsx ( item_id, revision_id, title ) values ( 18, 19, 'All About Revisions' ); -
Because a special trigger is generated for each content type +
Because a special trigger is generated for each content type that includes insert statements for all inherited tables, revisions -with extended attributes may be created in the same fashion:
+with extended attributes may be created in the same fashion: +
+insert into cr_imagesx ( item_id, revision_id, title, height, width ) values ( 18, 19, 'A Nice Drawing', 300, 400 ); -
Inserting content via file or text upload
Selecting a live revision
The live revision of a content item can be obtained with the -content_item.get_live_revision function:
+
+Inserting content via file or text upload
+Selecting a live revision
+The live revision of a content item can be obtained with the +content_item.get_live_revision function:
+live_revision_id := content_item.get_live_revision( item_id => :item_id ); -The item_id identifies the content item with which the -revision is associated.
Likewise, the most recent revision of a content item can be +
The item_id identifies the content item with which the +revision is associated.
+Likewise, the most recent revision of a content item can be obtained with the content_item.get_latest_revision -function:
+function: +
+latest_revision_id := content_item.get_latest_revision( item_id => :item_id ); -
karlg\@arsdigita.comLast Modified: $Id: revisions.html,v 1.1.1.1 2001/03/13 22:59:26 +
+karlg\@arsdigita.com +Last Modified: $Id: revisions.html,v 1.1.1.1 2001/03/13 22:59:26 ben Exp $
- Index: openacs-4/packages/acs-content-repository/www/doc/guide/search.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/guide/search.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-content-repository/www/doc/guide/search.adp 20 Aug 2015 17:19:50 -0000 1.2.2.1 +++ openacs-4/packages/acs-content-repository/www/doc/guide/search.adp 25 Aug 2015 18:02:05 -0000 1.2.2.2 @@ -2,28 +2,33 @@{/doc/acs-content-repository {Content Repository}} {Content Repository Developer Guide: Search} Content Repository Developer Guide: Search - - - Search
The content repository provides a consistent sitewide interface +
Search
+The content repository provides a consistent sitewide interface for searching content. It uses Intermedia to index the content column of cr_revisions) as well as all -the attribute columns for each content type.
Searching Content
The content column in cr_revisions may contain +the attribute columns for each content type.
+Searching Content
+The content column in cr_revisions may contain data in any text or binary format. To accomodate searches across multiple file types, the content repository uses an Intermedia index with the INSO filtering option. The INSO filter automatically detects the the file type of a binary object, and extracts text from it for indexing. Most common file types are supported, -including PDF and Microsoft Word, and Excel and PowerPoint.
Searching for content requires the same syntax as any text -index:
+including PDF and Microsoft Word, and Excel and PowerPoint. +
+Searching for content requires the same syntax as any text +index:
+select score(1), revision_id, item_id from cr_revisions r where contains(content, 'company', 1) > 0 -
The above query may be useful for an administrative interface +
The above query may be useful for an administrative interface where you wish to search across all revisions, but in most cases -you only want to search live revisions:
+you only want to search live revisions: +
+select score(1), revision_id, item_id, content_item.get_path(item_id) url, title from @@ -32,11 +37,15 @@ contains(content, 'company', 1) > 0 and revision_id = content_item.get_live_revision(item_id) -
The URL and title may be used to construct a hyperlink directly -to the item.
You may implement any number of variants on this basic query to +
The URL and title may be used to construct a hyperlink directly +to the item.
+You may implement any number of variants on this basic query to place additional constraints on the results, such as publication date, content type, subject heading or a particular attribute (see -below).
Some limitations of the current implementation include:
-
+below).
+
- Multilingual searches are not enabled by default. You may enable them for one more languages by setting the appropriate Intermedia preferences when creating @@ -47,10 +56,14 @@ be possible to specify an arbitrary function to return the path for items of a particular content type, with content_item.get_path as the default. -
Some limitations of the current implementation include:
+Searching Attributes
This task is primarily handled to two Intermedia indices:
Providing a generic mechanism for searching attributes is +
Searching Attributes
+This task is primarily handled to two Intermedia indices:
+Providing a generic mechanism for searching attributes is complicated by the fact that the attributes for each content type are different. The content repository takes advantage of the XML -features in Oracle 8.1.6 to address this:
-
+features in Oracle 8.1.6 to address this:
+
After creating a new revision and inserting attributes into the storage table for the content type and all its ancestors, you must execute the content_revision.index_attributes procedure. @@ -63,15 +76,19 @@ generate the XML document.
A special Intermedia index configured to parse XML documents is built on the column containing the XML documents for all revisions.
-
The Intermedia index allows you to use the WITHIN operator to -search on individual attributes if desired.
+
The Intermedia index allows you to use the WITHIN operator to +search on individual attributes if desired.
+select revision_id,score(1) from cr_revisions where contains(attributes, 'company WITHIN title', 1) > 0 -
Some limitations of the current implementation include:
-
+
+
- A USER_DATASTORE associated with each row of the cr_items table, which feeds Intermedia the contents of the content column (a BLOB) for the live revision of @@ -86,7 +103,10 @@ to reflect one-to-many relationships or special formatting of attributes as well. The handler should specify a java class and method, which a dispatch method can call by reflection. -
Some limitations of the current implementation include:
+
karlg\@arsdigita.com
+
+karlg\@arsdigita.com +
+ Last Modified: $Id: search.html,v 1.1.1.1 2001/03/13 22:59:26 ben Exp $ - Index: openacs-4/packages/acs-content-repository/www/doc/guide/storage.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/guide/storage.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-content-repository/www/doc/guide/storage.adp 20 Aug 2015 17:19:50 -0000 1.2.2.1 +++ openacs-4/packages/acs-content-repository/www/doc/guide/storage.adp 25 Aug 2015 18:02:05 -0000 1.2.2.2 @@ -2,18 +2,23 @@{/doc/acs-content-repository {Content Repository}} {} - - - Storing Data in the Content Repository
This document provides an introduction to using the content +
Storing Data in the Content Repository
+This document provides an introduction to using the content repository for storing data (binary or text files) and associated attributes. It describes how to store user portraits as an -example.
Define an Item Type
The first step towards using the content repository is to define +example.
+Define an Item Type
+The first step towards using the content repository is to define one or more content types for the data you wish to -manage.
The basic content item includes the following attributes:
-
+manage.
+
- Title
- Description
- Publication or Posting Date
- Author or Contributor
- MIME Type
- Binary or Text Data -
The basic content item includes the following attributes:
+Most types of content require additional attributes. For a +
Most types of content require additional attributes. For a photo, we probably also want to store the pixel width and height at -the very least:
+the very least: +
+create table images ( image_id integer constraint images_image_id_fk @@ -23,8 +28,10 @@ width integer, height integer ); -Content types are nothing more than standard ACS Objects that -inherit from content_revision:
+
+Content types are nothing more than standard ACS Objects that +inherit from content_revision:
+begin acs_object_type.create_type ( @@ -56,17 +63,22 @@ end; / show errors -
Note that content types always extend content_revision, +
Note that content types always extend content_revision, rather than content_item. This is because we want to store multiple revisions of both the actual data (in this case the image) as well as associated attributes (the width and height of the image -may vary among revisions).
Define a Relationship to a Target Object
The content repository implements a flexible mechanism for +may vary among revisions).
+Define a Relationship to a Target Object
+The content repository implements a flexible mechanism for organizing data in a hierarchical fashion in a manner similar to a file system. This would be useful if we ever decided to allow each user to manage an entire personal photo gallery rather than a -single portrait.
In the simple case where each user is allowed a single portrait, +single portrait.
+In the simple case where each user is allowed a single portrait, we can simply define a relationship between user and image as ACS -Objects:
+Objects: +
+acs_rel_type.create_role('user'); acs_rel_type.create_role('portrait'); @@ -81,13 +93,17 @@ min_n_rels_two => 0, max_n_rels_two => 1 ); -Note that the user object is related to a +
Note that the user object is related to a content_item object rather than an image object directly. Each image object represents only a single revision of a portrait. Revisions always exist in the context of an -item.
Store Objects
Now we have defined both a content type and relationship type, +item.
+Store Objects
+Now we have defined both a content type and relationship type, we can start storing portraits. The DML for processing a new -portrait upload form would look like this:
+portrait upload form would look like this: +
+begin transaction :item_id := content_item.new(:name, :item_id, sysdate, NULL, '[ns_conn peeraddr]'); # maybe have content_revision return the LOB locator so that it can @@ -96,8 +112,12 @@ :item_id, :revision_id); blob_dml_file update cr_revisions set content = empty_blob() ... :rel_id := acs_rel.new(...) -Retrieve Objects
+
+Retrieve Objects
+ns_ora write_blob ... -
karlg\@arsdigita.comLast Modified: $Id: storage.html,v 1.1.1.1 2001/03/13 22:59:26 +
+karlg\@arsdigita.com +Last Modified: $Id: storage.html,v 1.1.1.1 2001/03/13 22:59:26 ben Exp $
- Index: openacs-4/packages/acs-content-repository/www/doc/guide/template.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/guide/template.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-content-repository/www/doc/guide/template.adp 20 Aug 2015 17:19:50 -0000 1.2.2.1 +++ openacs-4/packages/acs-content-repository/www/doc/guide/template.adp 25 Aug 2015 18:02:05 -0000 1.2.2.2 @@ -4,82 +4,104 @@Content Repository Developer Guide: Applying Templates - - - Applying Templates
The content repository allows you to associate templates with +
Applying Templates
+The content repository allows you to associate templates with both content types and individual content items. A template determines how a content item is rendered when exported to the file -system or served directly to a client.
The content repository does not make any assumptions about the +system or served directly to a client.
+The content repository does not make any assumptions about the type of templating system used by the application server with which it is being used. Templates are simply made available to the application server as text objects. The server is responsible for -merging the template with the actual content.
Creating templates
The content repository handle templates as a special class of +merging the template with the actual content.
+Creating templates
+The content repository handle templates as a special class of text object. The interface for handling templates builds on that of -simple content items:
+simple content items: +
+template_id := content_template.new( name => 'image_template', parent_id => :parent_id ); -The name represents the tail of the location for that content +
The name represents the tail of the location for that content template. The parent ID must be another content item, or a subclass -of content item such as a folder.
+of content item such as a folder.
+The content_template.new function accepts the standard creation_date, creation_user, and -creation_ip auditing parameters.
Content items and templates are organized in two separate +creation_ip auditing parameters.
+Content items and templates are organized in two separate hierarchies within the content repository. For example, you may place all your press releases in the press folder under the item root (having the ID returned by content_item.get_root_folder). You may have 5 different templates used to render press releases. These my be stored in the press folder under the template root (having the -ID returned by content_template.get_root_folder).
Templates are placed under their own root to ensures that bare +ID returned by content_template.get_root_folder).
+Templates are placed under their own root to ensures that bare templates are never accessible via a public URL. This is also done because the relationship with the file system may be different for templates than for content items. For example, templates may be associated with additional code or resource files that developers -maintain under separate source control.
Associating templates with content types
You use the content_type.register_template procedure to -associate a template with a particular content type:
+maintain under separate source control. +
+Associating templates with content types
+You use the content_type.register_template procedure to +associate a template with a particular content type:
+content_type.register_template( content_type => 'content_revision', template_id => :template_id, use_context => 'public', is_default => 't' ); -
The use_context is a simple keyword that specifies the +
The use_context is a simple keyword that specifies the situation in which the template is appropriate. One general context, public, is loaded when the content repository is installed. Templates in this context are for presenting content to users of the site. Some sites may wish to distinguish this further, for example using intranet, extranet and -public contexts.
The is_default flag specifies that this template will +public contexts.
+The is_default flag specifies that this template will serve as the default template in the case that no template is registered to a content item of this content type and this use context. Any content type/context pair may have any number of templates registered to it, but there can be only one default -template per pair.
To make a template the default template for a content -type/context pair:
+template per pair. +
+To make a template the default template for a content +type/context pair:
+content_type.set_default_template( content_type => 'content_revision', template_id => :template_id, use_context => 'public' ); -Associating templates with content items
Individual items may also be associated with templates using the -content_item.register_template procedure:
+
+Associating templates with content items
+Individual items may also be associated with templates using the +content_item.register_template procedure:
+content_item.register_template( item_id => :item_id, template_id => :template_id, use_context => 'intranet' ); -
Unlike the case with content types, only one template may be -registered with a content item for a particular context.
The content management system uses this functionality to allow +
Unlike the case with content types, only one template may be +registered with a content item for a particular context.
+The content management system uses this functionality to allow publishers to choose templates for each content they create. For example, a company may have three different templates for presenting press releases. Depending on the subject, geographic region or any other criterion, a different template may be used for -each press release.
Retrieving the template for a content item
The application server (AOLserver or servlet container) may use +each press release.
+Retrieving the template for a content item
+The application server (AOLserver or servlet container) may use the content_item.get_template function to determine the proper template to use for rendering a page in any particular -context:
+context: +
+template_id := content_item.get_template( item_id => :item_id, use_context => 'public' @@ -88,23 +110,31 @@ template_path := content_template.get_path( template_id => :template_id ); -In the case that no template is registered to given item/context +
In the case that no template is registered to given item/context pair, content_item.get_template will return the default template (if it exists) for the related content type/context -pair.
Unregistering templates
The procedure for disassociating templates with content types is -as follows:
+pair. +
+Unregistering templates
+The procedure for disassociating templates with content types is +as follows:
+content_type.unregister_template( content_type => 'content_revision', template_id => :template_id, use_context => 'intranet' ); -The corresponding procedure to disassociate templates with -content items is:
+
+The corresponding procedure to disassociate templates with +content items is:
+content_item.unregister_template( item_id => :item_id, template_id => :template_id, use_context => 'admin' ); -
karlg\@arsdigita.comLast Modified: $Id: template.html,v 1.1.1.1 2001/03/13 22:59:26 +
+karlg\@arsdigita.com +Last Modified: $Id: template.html,v 1.1.1.1 2001/03/13 22:59:26 ben Exp $
- Index: openacs-4/packages/acs-content-repository/www/doc/guide/types.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/guide/types.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-content-repository/www/doc/guide/types.adp 20 Aug 2015 17:19:50 -0000 1.2.2.1 +++ openacs-4/packages/acs-content-repository/www/doc/guide/types.adp 25 Aug 2015 18:02:05 -0000 1.2.2.2 @@ -4,16 +4,19 @@Content Repository Developer Guide: Defining Content Types - - - Defining Content Types
The content repository requires you to define each type of +
Defining Content Types
+The content repository requires you to define each type of content supported by your supplication. Content types are defined as ACS Object Types, and may be created in the same fashion as any other object type. This page provides some specific examples and details related to defining ACS object types in the -context of the content repository.
Determine content attributes
A content item typically consists of two components:
-
+context of the content repository.
+
- Text or binary data stored as a single object
- Structured attributes stored as distinct values -
Determine content attributes
+A content item typically consists of two components:
+Note that a content type does not have to store its +
Note that a content type does not have to store its primary content in the BLOB column of the cr_revisions table. There is some additional overhead associated with retrieving small passages of text from the BLOB @@ -22,18 +25,22 @@ many items must be queried at the same time the difference may become significant. If the primary content will always be small, it is perfectly acceptable to store the content in an attribute column -instead.
Basic attributes for all content types are stored in the +instead.
+Basic attributes for all content types are stored in the cr_revisions (note that they are stored in the revisions table so that attributes may be updated for each new revision of the actual data). Most types of content require more than the basic attributes. For example, when storing images you will usually want to store the pixel height and width so that images can be selected -and sorted by size, as well as displayed efficiently.
Create an attribute table
Extended attributes associated with ACS object types may be +and sorted by size, as well as displayed efficiently.
+Create an attribute table
+Extended attributes associated with ACS object types may be stored as key-value pairs in a central table (generic storage), or in a custom table whose primary key references the associated ACS object ID (specific storage). To ensure efficient access to attributes, the content repository API requires you to use specific -storage. Your table should have the form:
+storage. Your table should have the form: +
+create table cr_content_type ( content_type_id integer constraint cr_content_type_id_fk @@ -42,12 +49,16 @@ primary key, attributes... ); -Note that your extended attribute table must reference the +
Note that your extended attribute table must reference the cr_revisions table, notcr_items. As mentioned above, this allows you to maintain multiple revisions of the attribute data in tandem with revisions of the content object -itself.
Use the Content Type API to create the content type
To define a content type, you should write an SQL script to -create the content type and then add attributes to it:
+itself. +
+Use the Content Type API to create the content type
+To define a content type, you should write an SQL script to +create the content type and then add attributes to it:
+declare attr_id acs_attributes.attribute_id%TYPE; begin @@ -72,14 +83,16 @@ ); ... -
The content_type methods use the core ACS Object Type +
The content_type methods use the core ACS Object Type API to create an object type for each content type, and to add attributes to the object type. In addition, content_type.create_type will create the extended attribute table with an appropriately defined primary key column (referencing its supertype) if the table does not already exist. Likewise, content_type.create_attribute will add a column -to the table if the column does not already exist.
Most importantly, the content_type methods call +to the table if the column does not already exist.
+Most importantly, the content_type methods call content_type.refresh_view after each change to the content type definition. Each content type must have an associated attribute view named @@ -89,9 +102,13 @@ acs_objects, cr_revisions, and all extended attribute tables in the class hierarchy of a particular content type. This view may be used to query attributes when serving -content.
Creating compund items
In many cases your content items will serve as containers for +content.
+Creating compund items
+In many cases your content items will serve as containers for other items. You can include the set of allowable components as part of a content type definition. See Object Relationships for -details.
templating\@arsdigita.comLast Modified: $Id: types.html,v 1.1.1.1 2001/03/13 22:59:26 ben +details.
+
+templating\@arsdigita.com +Last Modified: $Id: types.html,v 1.1.1.1 2001/03/13 22:59:26 ben Exp $
- Index: openacs-4/packages/acs-content-repository/www/doc/guide/workflow.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/guide/workflow.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-content-repository/www/doc/guide/workflow.adp 20 Aug 2015 17:19:50 -0000 1.2.2.1 +++ openacs-4/packages/acs-content-repository/www/doc/guide/workflow.adp 25 Aug 2015 18:02:05 -0000 1.2.2.2 @@ -2,11 +2,13 @@{/doc/acs-content-repository {Content Repository}} {Content Repository Developer Guide: Workflow} Content Repository Developer Guide: Workflow - - - Applying Workflow to Content Items
This document describes the workflow API calls necessary to -apply a simple workflow to a content item.
Workflow Description
Most publishers wish to follow some variation of the following -workflow:
+
+Applying Workflow to Content Items
+This document describes the workflow API calls necessary to +apply a simple workflow to a content item.
+Workflow Description
+Most publishers wish to follow some variation of the following +workflow:
+State Task Description @@ -18,23 +20,29 @@ Published None The publisher has approved the item. At any point in the workflow, an assigned user should be able to +
At any point in the workflow, an assigned user should be able to check out an item, such that other users are advised that someone is working on it. When checking an item in, a user should have up -to three options:
-
+to three options:
+
- Check the item in but do not mark the task as finished (allowing someone else to work on the task. The currently enabled task (whether it is authoring, editing or approving) does not change.
- Check the item in and move to the next task. For the authoring task, this signifies that the authoring is complete. For subsequent tasks, this signifies approval.
- Check the item in and move to a previous task, indicating rejection. -
This simple workflow is defined in -sql/workflows/author-edit-publish.sql.
Workflow Creation
Production of a content item frequently begins with a concept +
This simple workflow is defined in +sql/workflows/author-edit-publish.sql.
+Workflow Creation
+Production of a content item frequently begins with a concept which is initiated by the publisher and then executed by the staff. In this scenario, the publisher creates the workflow and then assigns each task in the workflow to one or more people. The API -calls to initialize a new workflow are as follows:
+calls to initialize a new workflow are as follows: +
+declare v_case_id integer; sample_object_id integer := 9; @@ -53,17 +61,23 @@ end; / -
In this case, only one assignment is made per task. You can make +
In this case, only one assignment is made per task. You can make as many assignments per task as desired. There is currently no workflow API to set deadlines, so you must write your own DML to insert a row into wf_case_deadlines if you wish to allow -the publisher to set deadlines ahead of time.
The above workflow is created in the Default context. In +the publisher to set deadlines ahead of time.
+The above workflow is created in the Default context. In practice, you may wish to create one or more contexts in which to create your workflows. Contexts may be used to represent different -departments within an organization.
The start_case enables the first task in the workflow, -in this case Authoring.
Check Out Item
If multiple persons are assigned to the same task, it is useful +departments within an organization.
+The start_case enables the first task in the workflow, +in this case Authoring.
+Check Out Item
+If multiple persons are assigned to the same task, it is useful to allow a single person to "check out" or lock an item while they -are working. This is accomplished with the following API calls:
+are working. This is accomplished with the following API calls: +
+declare v_journal_id integer; sample_task_id := 1000; @@ -77,14 +91,18 @@ end; / -
A mininum of two calls are required to perform any action +
A mininum of two calls are required to perform any action related to a task. In this case we are simply notifying the workflow engine that someone has started the task. You may specify NULL for the journal message if the user does not wish to comment -on the check out.
Check In Item
Unless given a timeout period, a lock on a content item will +on the check out.
+Check In Item
+Unless given a timeout period, a lock on a content item will persist until the holding user checks the item back in. This involves notifying the workflow engine that the user has finished -the task:
+the task: +
+declare v_journal_id integer; sample_task_id integer := 1000; @@ -99,14 +117,18 @@ end; / -
Upon finishing a task, you must notify the workflow engine where +
Upon finishing a task, you must notify the workflow engine where to go next. In this case, an author wishes to simply check an item back in without actually completing the authoring task. The set_attribute_value procedure must thus be used to set -next_place to the starting place of the workflow.
Finish Task
The process to finish a task varies slightly depending on +next_place to the starting place of the workflow.
+Finish Task
+The process to finish a task varies slightly depending on whether the user has previously checked out the item out or not. If the user has not already checked it out (has been working on the -item without locking it, the code looks like this:
+item without locking it, the code looks like this: +
+declare v_journal_id integer; sample_task_id integer := 1002; @@ -127,13 +149,17 @@ end; / -
In this case an author is finishing the Authoring task, +
In this case an author is finishing the Authoring task, upon which the workflow engine will move the workflow to the Authored state (as indicated by the next_place attribute). If the author had previously checked out the item, then -only the second step is required.
Approve or Reject
Approval steps more commonly do not involve an explicit +only the second step is required.
+Approve or Reject
+Approval steps more commonly do not involve an explicit check-out process. The code is thus virtually identical to that -above:
+above: +
+declare v_journal_id integer; sample_task_id integer := 1003; @@ -152,8 +178,12 @@ end; / -
Note the distinction between approval or rejection is determined -solely by the value of the next_place attribute.
karlg\@arsdigita.com
+Note the distinction between approval or rejection is determined +solely by the value of the next_place attribute.
+
+karlg\@arsdigita.com +
+ Last Modified: $Id: workflow.html,v 1.1.1.1 2001/03/13 22:59:26 ben Exp $ - Index: openacs-4/packages/acs-core-docs/lib/navfooter.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/lib/navfooter.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-core-docs/lib/navfooter.adp 25 Aug 2015 18:02:05 -0000 1.1.2.1 @@ -0,0 +1,16 @@ + + + \ No newline at end of file Index: openacs-4/packages/acs-core-docs/lib/navheader.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/lib/navheader.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-core-docs/lib/navheader.adp 25 Aug 2015 18:02:06 -0000 1.1.2.1 @@ -0,0 +1,71 @@ + + + \ No newline at end of file Index: openacs-4/packages/acs-core-docs/www/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/index.adp,v diff -u -N -r1.26 -r1.26.2.1 --- openacs-4/packages/acs-core-docs/www/index.adp 15 Jun 2015 11:16:44 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/index.adp 25 Aug 2015 18:02:06 -0000 1.26.2.1 @@ -1,100 +1,288 @@ -- OpenACS Documentation --
- -- - -OpenACS Core Documentation
--
-
- Part I: For Everyone -
- Part II: Administrator's Guide -
- Part III: Package Developer's Guide -
- Part IV: Platform Developer's Guide -
Primers and References
--
-
-
- API Browser -
- OpenACS CVS Browser -
- OpenACS tutorial -
- OpenACS FAQs -
- Learning OpenACS -
- AOLserver Documentation - (the Tcl Developer's Guide in particular.) -
- Tcl for Web Nerds -
- SQL for Web Nerds -
Documentation Improvement Project
- - --<% -# This block of ADP code ensures that the Installer can still serve this -# page even without a working templating system. - -set found_p 0 - -if {[db_table_exists apm_package_types]} { - db_foreach get_installed_pkgs "select package_key, pretty_name from apm_package_types order by upper(pretty_name) " { - if { ! $found_p } { - set found_p 1 - adp_puts "\n -Installed Packages
\n- \n"
- }
- set index_page [lindex [glob -nocomplain \
- "[acs_package_root_dir $package_key]/www/doc/index.*"] 0]
-
- if { [file exists $index_page] } {
- if {$pretty_name ne ""} {
- adp_puts "
- $pretty_name\n" - } else { - adp_puts "
- $package_key\n" - } - } else { - if {$pretty_name ne ""} { - adp_puts "
- $pretty_name\n" - } else { - adp_puts "
- $package_key\n" - } - } - } -} - - -if {!$found_p} { - adp_puts "
- No installed packages.\n" -} - adp_puts "
Uninstalled packages
\n- "
- foreach {key name} $packages {
- set index_page [lindex [glob -nocomplain \
- "[acs_package_root_dir $key]/www/doc/index.*"] 0]
- if { [file exists $index_page] } {
- adp_puts "
- $name\n" - } else { - adp_puts "
- $name\n" - } - } - adp_puts "\n
This software is licensed under the -GNU General Public License, version 2 (June 1991)
--Questions or comments about the documentation? -
- +
-Please visit the -OpenACS forums or send email to docs@openacs.org. -{/doc/acs-core-docs {Documentation}} {OpenACS Core Documentation} +OpenACS Core Documentation ++ + +++Table of Contents
-
+
- I. OpenACS For +Everyone
- II. Administrator's +Guide
-
+
- 2. +Installation Overview
- 3. +Complete Installation
- 4. +Configuring a new OpenACS Site
- 5. +Upgrading
- 6. +Production Environments
-
+
- Starting and Stopping an OpenACS +instance.
- AOLserver keepalive with +inittab
- Running multiple services on one +machine
- High +Availability/High Performance Configurations
- Staged +Deployment for Production Networks
- Installing SSL +Support for an OpenACS service
- Set up Log +Analysis Reports
- External uptime +validation
- Diagnosing +Performance Problems +
- 7. +Database Management
- 8. Backup +and Recovery
- A. Install +Red Hat 8/9
- B. +Install additional supporting software
-
+
- Unpack the +OpenACS tarball
- Initialize CVS +(OPTIONAL)
- Add PSGML +commands to emacs init file (OPTIONAL)
- Install +Daemontools (OPTIONAL)
- Install qmail +(OPTIONAL)
- Install +Analog web file analyzer
- Install +nspam
- Install Full Text Search +using Tsearch2
- Install Full Text Search +using OpenFTS (deprecated see tsearch2)
- Install +nsopenssl
- Install +tclwebtest.
- Install PHP for +use in AOLserver
- Install +Squirrelmail for use as a webmail system for +OpenACS
- Install +PAM Radius for use as external authentication
- Install +LDAP for use as external authentication
- Install AOLserver +3.3oacs1 +
- C. +Credits
- +
- III. For +OpenACS Package Developers
-
+
- 9. Development +Tutorial
- 10. +Advanced Topics
-
+
- Write the +Requirements and Design Specs
- Add the new +package to CVS
- OpenACS Edit This Page +Templates
- Adding +Comments
- Admin +Pages
- Categories
- Profile your +code
- Prepare +the package for distribution.
- Distributing upgrades of your +package
- Notifications
- Hierarchical data
- Using .vuh +files for pretty urls
- Laying +out a page with CSS instead of tables
- Sending +HTML email from your application
- Basic +Caching
- Scheduled Procedures
- Enabling WYSIWYG
- Adding +in parameters for your package
- Writing upgrade +scripts
- Connect to a second +database
- Future Topics +
- 11. Development +Reference
-
+
- OpenACS +Packages
- OpenACS Data Models +and the Object System
- The +Request Processor
- The OpenACS Database +Access API
- Using Templates in +OpenACS
- Groups, Context, +Permissions
- Writing OpenACS +Application Pages
- Parties in +OpenACS
- OpenACS Permissions +Tediously Explained
- Object +Identity
- Programming with +AOLserver +
- 12. +Engineering Standards
- 13. +Documentation Standards
- 14. +Internationalization
- D. Using CVS +with an OpenACS Site +
- IV. For OpenACS +Platform Developers
-
+
- 15. Kernel +Documentation
-
+
- Overview
- Object Model +Requirements
- Object +Model Design
- Permissions +Requirements
- Permissions Design
- Groups +Requirements
- Groups +Design
- Subsites Requirements
- Subsites +Design Document
- Package +Manager Requirements
- Package Manager +Design
- Database +Access API
- OpenACS +Internationalization Requirements
- Security Requirements
- Security +Design
- Security +Notes
- Request +Processor Requirements
- Request Processor +Design
- Documenting Tcl +Files: Page Contracts and Libraries
- Bootstrapping +OpenACS
- External Authentication +Requirements +
- 16. +Releasing OpenACS
- +
- Index +
+List of Figures
-
+
- 4.1. Site +Templates +
- 4.2. Granting +Permissions +
- 4.3. Granting +Permissions in 5.0 +
- 5.1. Upgrading with the +APM +
- 5.2. Upgrading a local +CVS repository +
- 6.1. Multiple-server +configuration +
- 6.2. Simple A/B Deployment +- Step 1 +
- 6.3. Simple A/B Deployment +- Step 2 +
- 6.4. Simple A/B Deployment +- Step 3 +
- 6.5. Complex A/B Deployment +- Step 1 +
- 6.6. Complex A/B Deployment +- Step 2 +
- 6.7. Complex A/B Deployment +- Step 3 +
- 6.8. Query +Analysis example +
- 8.1. Backup +and Recovery Strategy +
- 9.1. Assumptions in this +section +
- 9.2. Tutorial Data +Model +
- 9.3. The +Database Creation Script +
- 9.4. Database Deletion +Script +
- 9.5. Page +Map +
- 10.1. Upgrading +a local CVS repository +
- 11.1. Server file +layout diagram +
- 11.2. Package file +layout diagram + +
+List of Tables
-
+
- 2.1. Default +directories for a standard install +
- 2.2. Version +Compatibility Matrix +
- 5.1. Assumptions in this +section +
- 6.1. How it +Works +
- 10.1. table showing ETP +layout +
- 11.1. Package +files +
- 11.2. Context +Hierarchy Example +
- 11.3. acs_objects +example data +
- 14.1. Internationalization and +Localization Overview + +
++List of Examples
++ View comments +on this page at openacs.org Index: openacs-4/packages/acs-datetime/www/doc/coversheet.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-datetime/www/doc/coversheet.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-datetime/www/doc/coversheet.adp 20 Aug 2015 17:19:50 -0000 1.2.2.1 +++ openacs-4/packages/acs-datetime/www/doc/coversheet.adp 25 Aug 2015 18:02:06 -0000 1.2.2.2 @@ -2,21 +2,28 @@{/doc/acs-datetime {Date and Time Utilities}} {ACS DateTime} ACS DateTime - - ACS DateTime
-by ron\@arsdigita.comThis package provides a set of utilities for dealing with dates + +by ron\@arsdigita.com +
This package provides a set of utilities for dealing with dates and times. It provides a number of HTML form widgets for data and time entry, as well as procedures for calendar display and -navigation.
I. The Big Picture:
Many applications need to collect time and date information from +navigation.
+I. The Big Picture:
+Many applications need to collect time and date information from users. Constructing the HTML form elements to gather this information is tedious. The ACS DateTime package supplies a standard set of procedures to accomplish this, along with additional procedures to display (as HTML tables) various calendar -views.
II. Features:
-
+views.
+
- HTML form widgets for date and time entry with granularity ranging from seconds to months
- procedures that return calendar displays as HTML tables -
II. Features:
+III. Related Links:
-
+
III. Related Links:
+
ron\@arsdigita.com - +
+ron\@arsdigita.com Index: openacs-4/packages/acs-datetime/www/doc/design.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-datetime/www/doc/design.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-datetime/www/doc/design.adp 20 Aug 2015 17:19:50 -0000 1.2.2.1 +++ openacs-4/packages/acs-datetime/www/doc/design.adp 25 Aug 2015 18:02:06 -0000 1.2.2.2 @@ -2,17 +2,20 @@{/doc/acs-datetime {Date and Time Utilities}} {ACS DateTime} ACS DateTime - - ACS DateTime
+ by Ron Henderson -I. Essentials
This document describes the design of the ACS DateTime service -package.
II. Introduction
The ACS DateTime service is a collection of HTML widget +
I. Essentials
+This document describes the design of the ACS DateTime service +package.
+II. Introduction
+The ACS DateTime service is a collection of HTML widget generation procedures and date/time processing functions. The latter are built largely on top of the Tcl
clockroutines, although there are a small number of procedures that connect to the database for services like Julian date -conversions.Most the procedures defined within the ACS DateTime service take +conversions.
+Most the procedures defined within the ACS DateTime service take date/time information as input and return date/time strings to the caller. Rather than standardize on a low-level representation of time (like seconds since 00:00:00 UTC, January 1 1970) all of these @@ -22,8 +25,20 @@ Internally these are parsed by the standard Tcl procedure
clock scanfor processing and then converted back to a formatted string for output. This makes it easy to pass dates -between the Tcl layer and the database.III. Historical Considerations
This package was written largely to consolidate and improve the -date, time, and calendar functionality existing in ACS 3.
IV. Competitive Analysis
None.
VI. Data Model Discussion
The ACS DateTime package does not have a data model.
VII. Legal Transactions
None.
VIII. API
Date and Time functions
See examples.
-
+between the Tcl layer and the database.
+
-
dt_systimegenerates current system time (local or GMT) -
@@ -45,7 +60,10 @@
dt_interval_checkchecks the validity of a time interval by comparing start and end times and determining if they represent a positive, empty, or negative time range
- -
dt_widget_datetimegenerate HTML select widgets of varying granularity for collecting date and time information from @@ -54,9 +72,13 @@ for months of the year -
dt_widget_numeric_rangegenerates an HTML select widget for general numeric ranges
-
III. Historical Considerations
+This package was written largely to consolidate and improve the +date, time, and calendar functionality existing in ACS 3.
+IV. Competitive Analysis
+None.
+VI. Data Model Discussion
+The ACS DateTime package does not have a data model.
+VII. Legal Transactions
+None.
+VIII. API
+Date and Time functions
+See examples.
+Date and Time widgets
See examples.
-
+
Date and Time widgets
+See examples.
+Calendar widgets
See examples.
Each of the following allow the programmer to supply calendar +
Calendar widgets
+See examples.
+Each of the following allow the programmer to supply calendar details in an
ns_setkeyed on Julian date and returns -an HTML table.-
+an HTML table.
+
-
dt_widget_monthgenerates a basic monthly calendar -
@@ -73,9 +95,14 @@
dt_widget_calendar_navigationgenerates a calendar navigation widget with viewing options for day, week, month and year
-
XII. Future Improvements/Areas of Likely Change
Many of the calendar widgets generate extensive HTML from within +
XII. Future Improvements/Areas of Likely Change
+Many of the calendar widgets generate extensive HTML from within Tcl procedures. This will eventually be converted to a template-based system so that the display properties are more -easily customized.
XIII. Authors
Implemented by Ron Henderson (ron\@arsdigita.com), based on the -previous work of gregh\@arsdigita.com and smeeks\@arsdigita.com.
ron\@arsdigita.com - +easily customized. +XIII. Authors
+Implemented by Ron Henderson (ron\@arsdigita.com), based on the +previous work of gregh\@arsdigita.com and smeeks\@arsdigita.com.
+
+ron\@arsdigita.com Index: openacs-4/packages/acs-datetime/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-datetime/www/doc/index.adp,v diff -u -N -r1.2.2.2 -r1.2.2.3 --- openacs-4/packages/acs-datetime/www/doc/index.adp 21 Aug 2015 10:28:44 -0000 1.2.2.2 +++ openacs-4/packages/acs-datetime/www/doc/index.adp 25 Aug 2015 18:02:06 -0000 1.2.2.3 @@ -2,12 +2,18 @@{/doc/acs-datetime {Date and Time Utilities}} {ACS DateTime Documentation} ACS DateTime Documentation - - - ACS DateTime Documentation
ron\@arsdigita.comThis packages provides a set of utilities for dealing with dates -and times, including:
-
+
- widgets for date and time entry
- widgets for calendar display
- utilities for date and time formatting
- utilities for date and time conversions -
ACS DateTime Documentation
+ron\@arsdigita.com +This packages provides a set of utilities for dealing with dates +and times, including:
+Engineering Docs
-
+
Engineering Docs
+Release Notes
Please file bugs in the Bug Tracker.
Release Notes
+Please file bugs in the Bug Tracker.
+
+ron\@arsdigita.com Index: openacs-4/packages/acs-datetime/www/doc/requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-datetime/www/doc/requirements.adp,v diff -u -N -r1.2.2.6 -r1.2.2.7 --- openacs-4/packages/acs-datetime/www/doc/requirements.adp 21 Aug 2015 10:49:20 -0000 1.2.2.6 +++ openacs-4/packages/acs-datetime/www/doc/requirements.adp 25 Aug 2015 18:02:06 -0000 1.2.2.7 @@ -2,52 +2,73 @@{/doc/acs-datetime {Date and Time Utilities}} {ACS DateTime} ACS DateTime - - ACS DateTime Requirements
-by Ron HendersonI. Introduction
This document describes the requirements for the ACS DateTime -service package.
II. Vision Statement
ACS DateTime has the following primary functions:
-
+
+by Ron Henderson
+
- Allows applications to use a common set of procedures for collecting date and time information from users.
- Provides utilities to convert and format date and time information.
- Provides customizable form fragment widgets of varying degrees of temporal granularity through which applications can collect date and time information.
- Provides customizable calendar display widgets that allow applications to hook calendar information into a flexible display mechanism. -
I. Introduction
+This document describes the requirements for the ACS DateTime +service package.
+II. Vision Statement
+ACS DateTime has the following primary functions:
+Note that most of this functionality has existed within the ACS +
Note that most of this functionality has existed within the ACS for a long time, but it has been spread over a combination of ACS and module libraries. The ACS DateTime service packages brings these procedures into a common framework and provides for a more -consistent use of formatting conventions.
Note that these procedures do not make any specific reference to +consistent use of formatting conventions.
+Note that these procedures do not make any specific reference to timezone information and do not provide for conversion between timezones. This is left up to the application programmer. For information on timezone conversions see the ACS Reference service -package and specifically the timezone reference pack therein.
III. System/Application Overview
This service packages consists of a set of Tcl widget libraries +package and specifically the timezone reference pack therein.
+III. System/Application Overview
+This service packages consists of a set of Tcl widget libraries and other procedures for processing date and time information. These libraries are roughly separated into date-time and calendar -procedures.
IV. Use-cases and User-Scenarios
This package is only used as a procedural library for -applications.
V. Related Links
None.
VI. Requirements
Date and Time functions
-
+procedures.
+
- Generate current system time (local or GMT)
- Generate current system date
- Format a calendar time (system-dependent representation of time) using the formatting codes supported by the standard Unix time functions
- Generate a list of standard month names
- Generate a list of standard month abbreviations
- Convert Julian time to ANSI time (yyyy-mm-dd)
- Convert ANSI time to "pretty ANSI time" (yyyy-mm-dd to Month day, year)
- Generate a Tcl list of date-time elements (year, month, day, hour, minute, second)
- Check the validity of a time interval by comparing start and end times and determining if they represent a positive, empty, or negative time range -
- Generate HTML select widgets for collecting date and time information from users with varying granularity. Granularity should be optional and specified in units of seconds, minutes, fives (five minute intervals), quarters (fifteen minute intervals), halves (thirty minute intervals), hours, days, or months
- Generate an HTML select widget for months of the year
- Generate an HTML select widget for general numeric ranges -
IV. Use-cases and User-Scenarios
+This package is only used as a procedural library for +applications.
+V. Related Links
+None.
+VI. Requirements
+Date and Time functions
+Date and Time widgets
-
+
Date and Time widgets
+Calendar widgets
All of the following allow the programmer to supply calendar +
Calendar widgets
+All of the following allow the programmer to supply calendar details in an
ns_setkeyed on Julian date, and return -an HTML table.-
+an HTML table.
+
- Generate a basic monthly calendar
- Generate a small monthly calendar
- Generate small monthly calendars centered in a given month (previous, current, next)
- Generate a yearly calendar (composed of small montly calendars) given the starting month as a date
- Generate a yearly calendar based on calendar year (Jan to Dec), given any date within that calendar year
- Generate a calendar navigation widget with viewing options for day, week, month and year -
+
+ ron\@arsdigita.com - Index: openacs-4/packages/acs-developer-support/www/doc/developer-support-example.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-developer-support/www/doc/developer-support-example.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-developer-support/www/doc/developer-support-example.adp 25 Aug 2015 18:02:07 -0000 1.1.2.1 @@ -0,0 +1,562 @@ + +{/doc/acs-developer-support {Developer Support}} {Request Information} +Request Information ++ Request Information
+Your Workspace + : Admin +Home + : Developer Support + : Request +Information +Parameters
+
++
+ Request Start Time: Thu Jun 01 10:49:16 2000 (959870956) ++ Request Completion Time: Thu Jun 01 10:49:20 2000 (959870960) ++ Request Duration: 4077 ms ++ Method: GET ++ URL: /intranet/ad-index ++ +Query: (empty) +Headers
+
++
+ Connection: Keep-Alive ++ User-Agent: Mozilla/4.61 [en] (X11; U; Linux 2.2.12-20 i686) ++ Host: dev.arsdigita.com ++ Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, image/png, +*/* ++ Accept-Encoding: gzip ++ Accept-Language: en ++ Accept-Charset: iso-8859-1,*,utf-8 ++ +Cookie: last_visit=959374634; ad_browser_id=4608; +second_to_last_visit=959269200; +ad_user_login=1472%2cISotUu64GyYZUPdBdNVRWMsdVnRaFzwG; +ad_session_id=198622%2c1472%2cjbJ4dmbI8QQd5nSSobE%2e9c5H%2fQyOVs1v%2c959870956 +Output Headers
+
++
+ Set-Cookie: last_visit=959870956; path=/; expires=Fri, 01-Jan-2010 01:00:00 +GMT ++ Set-Cookie: second_to_last_visit=959374634; path=/; expires=Fri, +01-Jan-2010 01:00:00 GMT ++ MIME-Version: 1.0 ++ Date: Thu, 01 Jun 2000 14:49:20 GMT ++ Server: AOLserver/3.0+ad2 ++ Content-Type: text/html ++ Content-Length: 10715 ++ +Connection: close +Database Requests
+
++
+ Duration Command ++ + 1 ms gethandle -timeout -1 (returned nsdb0) ++ + 13 ms dml nsdb0 (main pool) + +
++update session_statistics +set session_count = session_count + 1, +repeat_count = repeat_count + 1 +where entry_date = trunc(sysdate) +
+ + 124 ms dml nsdb0 (main pool) + +
++update users +set last_visit = sysdate, + second_to_last_visit = last_visit, + n_sessions = n_sessions + 1 +where user_id = 1472 +
+ + 1 ms releasehandle nsdb0 (main pool) ++ + 1 ms gethandle (returned nsdb1) ++ + 6 ms 1row nsdb1 (main pool) + +
++select decode(count(1),0,0,1) + from user_group_map + where user_id=1472 + and (group_id=6 + or group_id=1181) +
+ + 1 ms releasehandle nsdb1 (main pool) ++ + 1 ms gethandle (returned nsdb2) ++ + 10 ms 0or1row nsdb2 (main pool) + +
++select group_id +from administration_info +where module = 'intranet' +and submodule is null +
+ + 13 ms 1row nsdb2 (main pool) + +
++select count(*) from user_group_map where user_id =1472 and group_id = 2 +
+ + 9 ms 0or1row nsdb2 (main pool) + +
++select group_id +from administration_info +where module = 'site_wide' +and submodule is null +
+ + 12 ms 1row nsdb2 (main pool) + +
++select multi_role_p from user_groups where group_id = 1 +
+ + 17 ms 1row nsdb2 (main pool) + +
++select decode(count(*), 0, 0, 1) from user_group_map where user_id = 1472 and group_id = 1 and role in ('administrator', 'all') ++ + 18 ms 0or1row nsdb2 (main pool) + +
++select first_names || ' ' || last_name as full_name, + decode(portrait_upload_date,NULL,0,1) as portrait_exists_p + from users + where user_id=1472 +
+ + 1225 ms select nsdb2 (main pool) + +
++select ug.group_name, ug.group_id + from user_groups ug, im_projects p + where ad_group_member_p ( 1472, ug.group_id ) = 't' + and ug.group_id=p.group_id + and p.project_status_id in (select project_status_id + from im_project_status + where project_status='Open' + or project_status='Future' ) + order by lower(group_name) +
+ + 1 ms getrow nsdb2 t39 (main pool) ++ + 2 ms getrow nsdb2 t39 (main pool) ++ + 1 ms getrow nsdb2 t39 (main pool) ++ + 1 ms getrow nsdb2 t39 (main pool) ++ + 1 ms getrow nsdb2 t39 (main pool) ++ + 2 ms getrow nsdb2 t39 (main pool) ++ + 1578 ms select nsdb2 (main pool) + +
++select ug.group_name, ug.group_id + from user_groups ug, im_customers c + where ad_group_member_p ( 1472, ug.group_id ) = 't' + and ug.group_id=c.group_id + and c.customer_status_id in (select customer_status_id + from im_customer_status + where customer_status in ('Current','Inquiries','Creating Bid','Bid out')) + order by lower(group_name) ++ + 2 ms getrow nsdb2 t54 (main pool) ++ + 30 ms 1row nsdb2 (main pool) + +
++select sum(hours) from im_hours where user_id=1472 + and on_which_table='im_projects' + and day >= sysdate - 7 +
+ + 14 ms 1row nsdb2 (main pool) + +
++select decode(count(1),0,0,1) + from user_groups ug + where ad_group_member_p ( 1472, ug.group_id ) = 't' + and ug.short_name='Business' +
+ + 15 ms 1row nsdb2 (main pool) + +
++select decode(count(1),0,0,1) + from user_groups ug + where ad_group_member_p ( 1472, ug.group_id ) = 't' + and ug.short_name='Finance' +
+ + 5 ms 1row nsdb2 (main pool) + +
++select sysdate - 30 from dual +
+ + 4 ms select nsdb2 (main pool) + +
++select newsgroup_id from newsgroups where scope = 'all_users' or scope = 'registered_users' or (scope = 'group' and group_id = 6) +
+ + 1 ms getrow nsdb2 t71 (main pool) ++ + 1 ms getrow nsdb2 t71 (main pool) ++ + 1 ms getrow nsdb2 t71 (main pool) ++ + 2 ms getrow nsdb2 t71 (main pool) ++ + 16 ms select nsdb2 (main pool) + +
++select news.title, news.news_item_id, news.approval_state, + expired_p(news.expiration_date) as expired_p, + to_char(news.release_date,'Mon DD, YYYY') as release_date_pretty +from news_items news, users ut +where creation_date > '2000-05-02' +and (newsgroup_id = 1 or newsgroup_id = 2 or newsgroup_id = 4) +and news.approval_state = 'approved' +and release_date < sysdate +and news.creation_user = ut.user_id +order by release_date desc, creation_date desc +
+ + 1 ms getrow nsdb2 t82 (main pool) ++ + 2 ms getrow nsdb2 t82 (main pool) ++ + 1 ms getrow nsdb2 t82 (main pool) ++ + 2 ms getrow nsdb2 t82 (main pool) ++ + 2 ms getrow nsdb2 t82 (main pool) ++ + 137 ms select nsdb2 (main pool) + +
++select g.group_name, g.group_id + from user_groups g, im_projects p, im_employees_active u, im_project_types + where p.project_lead_id = u.user_id + and p.project_type_id = im_project_types.project_type_id + and p.group_id=g.group_id + and p.requires_report_p='t' + and u.user_id='1472' + and p.project_status_id = (select project_status_id + from im_project_status + where project_status='Open') + and ( (lower(project_type) not in ('client - full service') + and not exists (select 1 + from general_comments gc + where gc.comment_date > sysdate - 7 + and on_which_table = 'user_groups' + and on_what_id = p.group_id)) or (lower(project_type) in ('client - full service') + and exists (select 1 + from survsimp_surveys + where short_name in ('project_report')) + and not exists (select 1 + from survsimp_responses + where survey_id=(select survey_id + from survsimp_surveys + where short_name in ('project_report')) + and submission_date > sysdate - 7 + and group_id=p.group_id)) ) ++ + 1 ms getrow nsdb2 t96 (main pool) ++ + 2 ms getrow nsdb2 t96 (main pool) ++ + 20 ms select nsdb2 (main pool) + +
++select distinct u.user_id + from users_active u, user_group_map ugm + where u.user_id = ugm.user_id + and ugm.group_id = 6 + and u.portrait is not null +
+ + 1 ms getrow nsdb2 t103 (main pool) ++ + 3 ms getrow nsdb2 t103 (main pool) ++ + 1 ms getrow nsdb2 t103 (main pool) ++ + 2 ms getrow nsdb2 t103 (main pool) ++ + 1 ms getrow nsdb2 t103 (main pool) ++ + 2 ms getrow nsdb2 t103 (main pool) ++ + 1 ms getrow nsdb2 t103 (main pool) ++ + 2 ms getrow nsdb2 t103 (main pool) ++ + 1 ms getrow nsdb2 t103 (main pool) ++ + 2 ms getrow nsdb2 t103 (main pool) ++ + 1 ms getrow nsdb2 t103 (main pool) ++ + 2 ms getrow nsdb2 t103 (main pool) ++ + 2 ms getrow nsdb2 t103 (main pool) ++ + 52 ms getrow nsdb2 t103 (main pool) ++ + 1 ms getrow nsdb2 t103 (main pool) ++ + 2 ms getrow nsdb2 t103 (main pool) ++ + 1 ms getrow nsdb2 t103 (main pool) ++ + 2 ms getrow nsdb2 t103 (main pool) ++ + 1 ms getrow nsdb2 t103 (main pool) ++ + 2 ms getrow nsdb2 t103 (main pool) ++ + 1 ms getrow nsdb2 t103 (main pool) ++ + 2 ms getrow nsdb2 t103 (main pool) ++ + 1 ms getrow nsdb2 t103 (main pool) ++ + 2 ms getrow nsdb2 t103 (main pool) ++ + 1 ms getrow nsdb2 t103 (main pool) ++ + 2 ms getrow nsdb2 t103 (main pool) ++ + 1 ms getrow nsdb2 t103 (main pool) ++ + 4 ms getrow nsdb2 t103 (main pool) ++ + 1 ms getrow nsdb2 t103 (main pool) ++ + 3 ms getrow nsdb2 t103 (main pool) ++ + 1 ms getrow nsdb2 t103 (main pool) ++ + 2 ms getrow nsdb2 t103 (main pool) ++ + 1 ms getrow nsdb2 t103 (main pool) ++ + 2 ms getrow nsdb2 t103 (main pool) ++ + 1 ms getrow nsdb2 t103 (main pool) ++ + 4 ms getrow nsdb2 t103 (main pool) ++ + 1 ms getrow nsdb2 t103 (main pool) ++ + 2 ms getrow nsdb2 t103 (main pool) ++ + 1 ms getrow nsdb2 t103 (main pool) ++ + 2 ms getrow nsdb2 t103 (main pool) ++ + 2 ms getrow nsdb2 t103 (main pool) ++ + 2 ms getrow nsdb2 t103 (main pool) ++ + 8 ms getrow nsdb2 t103 (main pool) ++ + 16 ms getrow nsdb2 t103 (main pool) ++ + 1 ms getrow nsdb2 t103 (main pool) ++ + 2 ms getrow nsdb2 t103 (main pool) ++ + 1 ms getrow nsdb2 t103 (main pool) ++ + 2 ms getrow nsdb2 t103 (main pool) ++ + 2 ms getrow nsdb2 t103 (main pool) ++ + 33 ms 0or1row nsdb2 (main pool) + +
++select u.first_names || ' ' || u.last_name as name, u.bio, u.skills, + ug.group_name as office, ug.group_id as office_id + from im_employees_active u, user_groups ug, user_group_map ugm + where u.user_id = ugm.user_id(+) + and ug.group_id = ugm.group_id + and ug.parent_group_id = 5 + and u.user_id = 1678 + and rownum < 2 +
+ + 12 ms select nsdb2 (main pool) + +
++select ug.group_id, ug.group_name, ai.url as ai_url +from user_groups ug, administration_info ai +where ug.group_id = ai.group_id +and ad_group_member_p ( 1472, ug.group_id ) = 't' +
+ + 1 ms getrow nsdb2 t207 (main pool) ++ + 119 ms getrow nsdb2 t207 (main pool) ++ + 1 ms releasehandle nsdb2 (main pool) ++ + 1 ms gethandle log (returned nsdb3) ++ + 11 ms 1row nsdb3 (log pool) + +
++select ad_group_member_p(1472, system_administrator_group_id) from dual +
+ + 1 ms releasehandle nsdb3 (log pool) ++ +3678 ms (total) +
+ +webmaster\@dev.arsdigita.com +Last Modified: $Id: developer-support-example.html,v 1.1.1.1 +2001/04/20 20:51:09 donb Exp $
Index: openacs-4/packages/acs-developer-support/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-developer-support/www/doc/index.adp,v diff -u -N -r1.2.2.3 -r1.2.2.4 --- openacs-4/packages/acs-developer-support/www/doc/index.adp 21 Aug 2015 10:49:20 -0000 1.2.2.3 +++ openacs-4/packages/acs-developer-support/www/doc/index.adp 25 Aug 2015 18:02:07 -0000 1.2.2.4 @@ -1,76 +1,82 @@ -{/doc/acs-developer-support {Developer Support}} {Developer Support} -Developer Support +{/doc/acs-developer-support {Developer Support}} {ACS Developer Support} +ACS Developer Support - - - Developer Support
-part of the ArsDigita Community System, by Jon Salz-
+
- Admin interface: /www/admin/monitoring/request-info.tcl
- Procedures: /packages/developer-support-procs.tcl, with support
in:
- /tcl/ad-abstract-url.tcl
- /tcl/ad-defs.tcl.preload
- /tcl/ad-security.tcl.preload
-
ACS Developer Support
+part of the ArsDigita Community System, by +Jon Salz +
+The Big Picture
-Software development is a big feedback loop: a developer writes +The Big Picture
+Software development is a big feedback loop: a developer writes something, tests it, and then repeats until the results are satisfactory. It's important to streamline this cycle by having a development environment which makes it easy to analyze what the -software is doing under the hood. -
Peeking Under the Hood
Our development environment previously consisted largely of +software is doing under the hood.
+Peeking Under the Hood
+Our development environment previously consisted largely of Emacs, and tail -f /web/servername/log/servername-error.log. Now this has been augmented: ad_footer and ad_admin_footer now display a link entitled Developer Information. (You can use the ds_link procedure to generate the link yourself.) Following the link displays a screenful of information -including:
-
+including:
+
- The times that the request started and ended, and its duration (with millisecond accuracy).
- The request parameters (method, url, query, headers, etc.).
- The output headers, if any.
- Information about all database queries performed while loading the page, including their respective durations (with millisecond accuracy). -
In addition, the ClientDebug facility of AOLserver 2 has been +
In addition, the ClientDebug facility of AOLserver 2 has been re-implemented in the abstract URL system (which serves nearly all non-static pages). If an error occurs while serving a page, a stack -trace is printed out.
Note that these nifty features pop up only when you are logged +trace is printed out.
+Note that these nifty features pop up only when you are logged in as a site-wide administrator! Revealing this information to -anyone else would pose a huge security risk.
Comments
-Tired of using ns_log to instrument your code, then +anyone else would pose a huge security risk. +Comments
+ +Tired of using ns_log + to instrument your code, then grokking the error log to see what's wrong with your page? Use the -ds_comment routine instead: +ds_comment + routine instead:
+ Your comment will show up at the bottom of the page, beneath the -Developer Information link (but only for site-wide +Developer Information + link (but only for site-wide administrators). It will also be displayed on the Developer Information page itself. -ds_comment "Foo is $foo"
Comments are displayed even if an error occurs in the page!
Enabling It
-Add the following to your parameters/yourservername.ini -file: -
-Note that you may not want to enable this stuff for production -systems - they probably incur a slight performance hit (although -this hasn't been benchmarked). +-[ns/server/yourservername/acs/developer-support] -; remember information about connections, for developers' benefit? -EnabledP=1 -; remember information about every database request? -DatabaseEnabledP=1 -; remember information for which client hosts? -EnabledIPs=* -; remember this information for how long? sweep how often? (in seconds) -DataLifetime=900 -DataSweepInterval=900 -
Comments are displayed even if an error occurs in the page!
+Enabling It
+Load the packate acs-developer-support via package manager, +browse to /ds and enable the desired options.
+Be careful of you enable developer support on busy production +systems - they probably incur a performance hit.
How It Works
-The security subsystem registers preauth and trace filters which +The security subsystem registers preauth and trace filters which store relevant connection information in shared variables (nsvs). The security subsystem also renames the AOLserver ns_db procedure and registers a wrapper which aggregates -information about database queries. -
Release Notes
Please file bugs in the Bug Tracker.
jsalz\@mit.eduLast Modified: $Id: index.html,v 1.1.1.1.28.1 2015/08/21 +information about database queries.
++Example output of ACS +Developer Support.
+Release Notes
+Please file bugs in the Bug Tracker.
+
+jsalz\@mit.edu +Last Modified: $Id: index.html,v 1.1.1.1.28.1 2015/08/21 10:28:44 gustafn Exp $
- Index: openacs-4/packages/acs-events/www/doc/design.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-events/www/doc/design.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-events/www/doc/design.adp 20 Aug 2015 17:19:51 -0000 1.2.2.1 +++ openacs-4/packages/acs-events/www/doc/design.adp 25 Aug 2015 18:02:07 -0000 1.2.2.2 @@ -2,45 +2,56 @@{/doc/acs-events {ACS Events}} {ACS Events Design Documentation} ACS Events Design Documentation - - ACS Events Design Documentation
-by W. Scott MeeksI. Essentials
-
+
+by W. Scott Meeks
+
- Tcl script directory (link to the API browser page for the package)
- PL/SQL file (link to the API browser page for the package)
- Data model: acs-events-create.sql
- Requirements document
- ER diagram
- Transaction flow diagram -
+I. Essentials
+II. Introduction
The ACS events service is primarily intended for use by writers +
II. Introduction
+The ACS events service is primarily intended for use by writers of application packages and other service packages. The service allows developers to specify and manipulate relationships (possibly recurring) between a set of intervals in time, an activity, and an arbitrary number of parties. An activity can be associated with an arbitrary number of ACS -objects.
The package doesn't provide for any interpretation of events, +objects.
+The package doesn't provide for any interpretation of events, leaving that up to the applications that use the service. In particular, the package assumes that permissioning, and the related concept of approval, will be handled by the application. Similarly, notification is also the responsibility of the application (but probably via another service package.) Likewise, the package -provides no UI support.
Possible application domains include include calendaring, room +provides no UI support.
+Possible application domains include include calendaring, room reservation, scheduling, project management, and event -registration.
The requirements break the functionality into four main areas: +registration.
+The requirements break the functionality into four main areas: events, time intervals, activities, and recurrences. The package meets the requirements for each of these areas in the following -ways:
+ways:
+Events: The service creates a new subtype of acs_object: acs_event. It creates an auxiliary table for mapping events to parties. It provides an API for manipulating and querying events and their associated time interval sets, activities, recurrences, -and parties.
+and parties.
+Time Intervals: The service creates tables for storing time intervals and sets of time intervals. It provides an API for manipulating and querying time intervals and time interval -sets.
+sets.
+Activities: The service creates a new subtype of acs_object: acs_activity. It creates an auxiliary table for mapping activities to objects. It provides an API for manipulating -activities, their properties, and their associated objects.
+activities, their properties, and their associated objects.
+Recurrences: The service creates a table for storing information on how an event recurs, including how the event recurs and when it stops recurring. It provides an API for manipulating @@ -50,24 +61,29 @@ event. This is done by only partially populating the recurrences for certain events. The service also provides a view which simplifies querying to find partially populated recurring events -that need recurrences added to the DB.
III. Historical Considerations
There are number of historical considerations surrounding the +that need recurrences added to the DB.
+III. Historical Considerations
+There are number of historical considerations surrounding the design of recurring events. Much of the current design can be traced pack to the original ACS 3.4 Calendar Package design, though the design has been cleaned up, modified to fit with the new events data model and slightly -expanded.
One key consideration is exactly how recurring events are +expanded.
+One key consideration is exactly how recurring events are supported. There are two main choices. One choice is to insert only a single row for each recurring event, regardless of the number of times it will recur. This row contains all the information necessary to compute whether or not that event would recur on a particular day. The alternative is to insert a row for each -recurrence.
I favored the second approach for the following reasons. First, +recurrence.
+I favored the second approach for the following reasons. First, one tradeoff is time vs. space. Computation, particularly if it might need to be done in Tcl and not solely in the database, is relatively expensive compared to storing additional information in the database. In many cases, the only information that will need to be stored for recurrences is the date and time of the -recurrence.
I think it may be faster in Oracle even with a stored proc, at +recurrence.
+I think it may be faster in Oracle even with a stored proc, at least with the month view and possibly the week view as well. This is because with 1 row per recurrence, the month and week view queries can pull all the relevant items out at once and can take @@ -76,7 +92,8 @@ each day (up to 42 in the month view), calling the check repeat proc for each base repeating item who's repeat_until date was still relevant, and then effectively constructing the item to be -displayed.
Another reason is that the first approach, to insert only a +displayed.
+Another reason is that the first approach, to insert only a single row, seems to require a significantly more complex design. Thus the design, implementation and eventual maintenance time would be greater. It becomes even more complex when you allow exceptions. @@ -85,33 +102,39 @@ the check repeat proc is called. It the worst case, every recurrence is an exception, so you're essentially back to 1 row per recurrence, plus all the added complexity of using the check repeat -proc.
This is not an unreasonable possibility and is in fact how Sloan +proc.
+This is not an unreasonable possibility and is in fact how Sloan operates. Each class is represented as a recurring item and it is very common for each instance to have a different set of files -attached to it.
However, there are drawbacks to this approach. First, it will be +attached to it.
+However, there are drawbacks to this approach. First, it will be more difficult to handle events that recur indefinitely. Second (but related) is that safeguards will need to be put in place to prevent pathological (accidental or intentional) cases from -swamping the database.
In the ACS 3.4 Calendar Package, this was partially resolved in +swamping the database.
+In the ACS 3.4 Calendar Package, this was partially resolved in the following way. Users are limited to looking no more than 10 years in the past or 10 years in the future. (Actually, this is a system parameter and can be set more or less restrictive, but the default is 10 years.) This seemed reasonable given that other systems seem to have arbitrary, implementation driven limits. Yahoo and Excite have arbitrary limits between about 1970 and 2030. Palm -seems to have no lower limit, but an upper limit of 2031.
The 4.0 ACS Events service doesn't enforce a particular policy +seems to have no lower limit, but an upper limit of 2031.
+The 4.0 ACS Events service doesn't enforce a particular policy to prevent problems, but it does provide mechanisms that a well-designed application can use. The keys are the event_recurrence.insert_events procedure and the -partially_populated_events view.
+partially_populated_events view.
+insert_events takes either an event_id or a recurrence_id and a cutoff date. It either uses the recurrence_id, or gets it from the event_id, to retrieve the information needed to generate the dates of the recurrences. When inserting a recurring event for the first time, the application will need to call insert_events with a reasonable populate_until date. For calendar, for example, this could be sysdate + the lookahead -limit.
It is the application's responsibility to determine if +limit.
+It is the application's responsibility to determine if additional events need to be inserted into the DB to support the date being used in a query to view events. The application can do this by querying on partially_populated_events, using the date in @@ -122,7 +145,8 @@ current date viewed and the maximum date viewed so as to minimize the number of times this query is performed. The application should also pick a date reasonably far in the future for insert additional -instances.
Another historical consideration is the choice of values for +instances.
+Another historical consideration is the choice of values for event_recurrence.interval_type. The original choice for the 3.4 calendar was based on the Palm DateBook which seemed fairly inclusive (covering both Yahoo Calendar and Excite Planner) though @@ -133,7 +157,8 @@ application to generate an arbitrary recurrence function. The function must take a date and a number of intervals as arguments and return a new date greater than the given date. The number of -intervals is guaranteed to be a positive integer.
For the days_of_week column, the representation chosen, a +intervals is guaranteed to be a positive integer.
+For the days_of_week column, the representation chosen, a space-delimited list of integers, has a number of advantages. First, it is easy and reasonably efficient to generate the set of dates corresponding to the recurrences. insert_events takes @@ -142,59 +167,83 @@ are equivalent and the translations to and from UI are straightforward. In particular, the set of checkboxes corresponding to days of the week are converted directly into a Tcl list which -can be stored directly into the DB.
IV. Competitive Analysis
Since this is a low level service package, there is no direct -competition.
V. Design Tradeoffs
Because this is a service package, tradeoffs were made only in +can be stored directly into the DB.
+IV. Competitive Analysis
+Since this is a low level service package, there is no direct +competition.
+V. Design Tradeoffs
+Because this is a service package, tradeoffs were made only in areas of interest to developers. Indeed, the main design tradeoff was made at the very beginning, namely that this would be a narrowly-focussed service package. This had consequences in the -following areas:
Maintainability
To simplify the package as much as possible, a number of +following areas:
+Maintainability
+To simplify the package as much as possible, a number of possible features were left to be handled by other services or by the applications using the events package. This includes controlling access to events via permissions, providing an approval process, and providing support for notification. permissions app dependent, approval via workflow, separate notification service -package
There was one significant, fairly complex feature that was +package
+There was one significant, fairly complex feature that was included, namely the support for recurrences. It could have been left to the application developers or another service package. However, because the 3.4 Calendar package already had a model for recurring calendar items, it was straightforward to adapt this model for the rest of the events data model. The advantage of this is that this code is now in one place with no need for applications to reinvent the wheel. It also means that there is a consistent -model across the toolkit.
Reusability
Much thought was given to the needs of applications most likely +model across the toolkit.
+Reusability
+Much thought was given to the needs of applications most likely to use this service, such as calendar, events, and room reservations. This has led to a well defined API which should be -reusable by most applications that are concerned by events.
Testability
Because the API consists of well defined PL/SQL functions, it +reusable by most applications that are concerned by events.
+Testability
+Because the API consists of well defined PL/SQL functions, it should be fairly easy to build a test suite using the PL/SQL -testing tools.
VI. Data Model and API Discussion
The data model and PL/SQL API encapsulate the four main +testing tools.
+VI. Data Model and API Discussion
+The data model and PL/SQL API encapsulate the four main abstractions defined in the ACS Events service: events, time interval sets, activities, and recurrences. At present, there is no Tcl API, but if desired one could be added consisting primarily of -wrappers around PL/SQL functions and procedures.
Events
This is the main abstraction in the package. acs_event +wrappers around PL/SQL functions and procedures.
+Events
+This is the main abstraction in the package. acs_event is a subtype of acs_object. In addition to the acs_events table, there is an acs_event_party_map table which maps between parties and events. The acs_event package defines new, delete, various procedures to set attributes and recurs_p indicating whether or not a -particular event recurs.
Time Interval Sets
Because time interval sets are so simple, there is no need to +particular event recurs.
+Time Interval Sets
+Because time interval sets are so simple, there is no need to make them a subtype of acs_object. Interval sets are represented with one table to represent time intervals, and a second table which groups intervals into sets, with corresponding PL/SQL packages defining new, delete, and -additional manipulation functions.
Activities
This is the secondary abstraction in the package. +additional manipulation functions.
+Activities
+This is the secondary abstraction in the package. acs_activity is a subtype of acs_object. In addition to the acs_activities table, there is an acs_activity_object_map table which maps between objects and activities. The acs_activity package defines new, delete, and various procedures to set -attributes and mappings.
Recurrences
Since recurrences are always associated with events, there +attributes and mappings.
+Recurrences
+Since recurrences are always associated with events, there seemed to be no need to make them objects. The information that determines how an event recurs is stored in the -event_recurrences table.
The event_recurrence package defines new, +event_recurrences table.
+The event_recurrence package defines new, delete, and other procedures related to recurrences. The -key procedure is insert_events.
A view, partially_populated_events, is created which +key procedure is insert_events.
+A view, partially_populated_events, is created which hides some of the details of retrieving recurrences that need to -populated further.
VIII. User Interface
This package does not provide a UI.
IX. Configuration/Parameters
There are no parameters for this package.
X. Future Improvements/Areas of Likely Change
If the system presently lacks useful/desirable features, note +-->
VIII. User Interface
+This package does not provide a UI.
+IX. Configuration/Parameters
+There are no parameters for this package.
+X. Future Improvements/Areas of Likely Change
+If the system presently lacks useful/desirable features, note details here. You could also comment on non-functional improvements -to the package, such as usability.
Note that a careful treatment of the earlier "competitive +to the package, such as usability.
+Note that a careful treatment of the earlier "competitive analysis" section can greatly facilitate the documenting of this -section.
XI. Authors
-
+section.
+
- System owner: W. Scott Meeks
- System creator: W. Scott Meeks
- Documentation author: W. Scott Meeks -
- It saves work and increases quality; applications that deal with time don't have to "re-invent the wheel" but instead can use a common, tested code base.
- It improves consistency; the same API will be used in different applications.
- It simplifies integration; since a common data model is used to represent events, different applications can more easily share related information. -
- System/Package "coversheet" TBD
- Design document TBD
- Developer's guide TBD
- User's guide TBD
- 3.4 calendar package documentation
- Reservations module
- Problem Set 2 revised for ACS 4.0
- Test plan TBD -
- User directory: none
- ACS administrator: acs-lang
- Subsite administrator directory: none
- Tcl script directory: /api-doc
- PL/SQL file:
- Data model:
- Requirements document -
- Performance: availability and efficiency
For Internationalization to be effective, it needs to be integrated into every module in the system. Thus making the @@ -24,6 +28,7 @@ on matching of template files for locales.
- Flexibility
- Interoperability
- Reliability and robustness
- Usability
- Maintainability
- Portability
@@ -35,7 +40,11 @@
A set of unit tests are included in the acs-lang package, to allow automatic testing after installation.
- -
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, @@ -118,6 +148,7 @@ template.
- 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. @@ -204,46 +253,59 @@ foo.en.adp, use that.
- If no locale-specific template is found, look for a simple .adp file, such as foo.adp. -
- Lookup is tried with language and key without package prefix.
- fconfigure -encoding blah
- content type in outputheaders set for encoding conversion
ad_proc adp_parse_ad_conn_file {} { @@ -521,10 +632,16 @@
- - System creator
- System owner: hqm\@arsdigita.com
- Documentation author: hqm\@arsdigita.com -
- One code base for the world
- English is just another language -
- A developer needs to author a web site/application in a @@ -95,8 +109,12 @@ such as message catalogs, non-text assets such as graphics, and use of templates which help to separate application logic from presentation. -
- 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 @@ -109,12 +127,16 @@ Part 1: Country codes http://www.niso.org/3166.html - Test plan
- Competitive system(s) -
- Loading source files (.tcl or .adp) or content files from the filesystem
- Accepting form input data from users
- Delivering text output to a browser
- Composing an email message
- Writing data to the filesystem -
- If a user received his last mail X days ago without any further bounced mail then his bounce-record gets deleted since it can be assumed that his email account is working again and no longer @@ -47,6 +51,7 @@ times (configurable) that contains a link to reenable the email account.
- Edit /etc/postfix/main.cf @@ -58,9 +63,10 @@ you leave the parameter as it was) to "nsadmin" (in case you only run one server).
- A single data model for representing message objects. Message objects model electronic messages between users of a collaborative system. Mail messages, USENET news messages, Bboard messages, user comments are all examples of applications that might use message objects.
- Storage of message objects.
- Central support for attachments, threading, and search.
- Mechanisms for sending and receiving message objects as e-mail. -
- A data model for representing and storing messages.
- A data model for representing and storing attachments to messages.
- A mechanism for sending messages as e-mail.
- A mechanism for integrating the message store into site wide search. -
- BBoard
- Webmail
- General Comments
- Spam
- Various parts of the ticket tracker. -
- Bboard organizes messages into forums and categories and threads. It also allows users to send and reply to messages via e-mail.
- Webmail organizes messages into mail folders.
- General comments attaches messages to objects representing static or other content.
- Spam queues messages and sends them to groups of people as e-mail. -
- Reply chaining and threading.
- Messages with attachments of various types.
- Representing messages as multipart MIME e-mail.
- Queuing and sending messages as e-mail. -
- No easy way to find out what reference data even existed.
- No way to find out how old the data was.
- No way to find out where that data came from.
- Very US/English slant on the data. -
- This system was designed with maintainability and reusability as its primary goals. By wrapping a layer around all of the reference tables we have increased the maintainability immensely.
- Another goal was to bring together many different types of data and present them in a logical fashion. It was amazing how little of this data is available on the internet in a database friendly form. -
- It allows applications to refer to and employ a common set of reference data.
- It gives administrators the ability to run standard reports on this data.
- It offers a convenient repository for and the ability to run reports on data of this sort.
- It allows us to monitor the usage of reference data. -
- Geographic data: zip codes, country codes and states/provinces
- Standards bodies data: ISO 4217 currency codes, ISO 3166 Country Codes, ITU Vehicle Signs
- Quasi-Standards: S&P Long-term Issuer Credit Ratings
- Internal: Status Codes, Employee Position Codes -
- A standard framework for monjitoring and modifying reference data.
- A method of determining whether or not that data is expired.
- The ability to include not only the data but also functions to work with that data. -
- The reference package should note this change.
- The appropriate table is updated. In this case countries et al.
- An update to the repository database field effective_date is added.
- A diff type of entry into the reference repository @@ -78,8 +103,8 @@ effective date and be able to handle the change as needed (i.e. simply read the new table).
- Historical data will be available using this diff for those applications that need to use the old data -
- contract - analagous to interface, contracts serve as logical containers for operations.
- operation - a method of an interface. defines a method signature, including both input and outputs as well as metadata @@ -30,41 +40,77 @@ fufills a given operation of the contract.
- bindings - association between an interface and an implementation.
- types - define the kind of input and outputs a operation recieves. -
- (sql):: acs_sc_msg_type__new (name, spec):
+already installed on the system can be bound to it.
+
Api Reference
+[for oracle please syntax replace __ with .]
+Creating Message Types
+- (sql):: acs_sc_msg_type__new (name, spec):
defines a type based on spec. Spec should be a string (possibly emtpy) that defines the names and types that compose this type. example
-ObjectDisplay.Name.InputTypeas nameobject_id:integeras spec.
Creating Interfaces
- (sql): +
Creating Interfaces
+- (sql):
acs_sc_contract__new (contract_name, contract_desc):-
creates a new contract to serve as a logical container for +
- (sql):: acs_sc_msg_type__new (name, spec):
- (sql):
+contract.
+
- (sql):
acs_sc_operation__new (contract_name, operation_name, operation_desc, operation_iscachable_p, operation_inputtype, operation_outputtype ):-
creates a new operation as part of a contract.
Creating Implementations
- (tcl) acs_sc_proc (contract, operation, impl): registers an -implementations. ?? why operation
Discovery
- (tcl) acs_sc_binding_exists_p (contract, impl): returns boolean +
creates a new operation as part of a contract.
+Creating Implementations
+- (tcl) acs_sc_proc (contract, operation, impl): registers an +implementations. ?? why operation
Discovery
+- (tcl) acs_sc_binding_exists_p (contract, impl): returns boolean whether a binding exists between a given contract name and -implmentation.
Dispatching
- (tcl) acs_sc::invoke (contract, operation, [arguments, impl]): -calls an operation
Examples
Included in the service contract package are examples for oracle -and postgresql of a trivial contract.
Also the search contract functions as a non-trivial core -contract used by openacs4.
Further Reading
Abstract Factory Pattern - GOF
Component Systems - Clemens Syzperski
WSDL Spec
Release Notes
Please file bugs in the Bug Tracker.
Credits
Most content was provided by Neophytos Demetriou. Most of the +implmentation.
- (sql):
- (tcl) acs_sc::invoke (contract, operation, [arguments, impl]): +calls an operation
- Go to /admin/group-types and select "Developer defined test types"
- Add a permissible rel type of Membership Relation
- Add a group named "Test group" -
- Click on group types
- Click on Groups
- Click on "Group name" under "Attributes of this type of group"
- Ensure that you see the properties of the attribute and that you are offered no administrative links
- Make sure you cannot add attributes or do anything under @@ -101,7 +108,10 @@ not deleted
- Click on nuke this group then click yes. Group should no longer show up
- Recreate the group Foobar
- Click on foobar, then change the name to "ArsDigita"
- Change ArsDigita's join policy to closed -
- Click on "Define a new group type" and create a new group type called "Project" with type "project". Ensure that all the fields you see are required (try submitting without entering in @@ -136,7 +146,9 @@ you get a link back to add a relationship type. Add back the composition relation.
- Add a group of type project named GuideStar.org -
- Create a new relationship type, Employment relation, that is a subtype of Membership relation, between group and person. Group has role of employer, person role of employee.
- Select the employment relation and add an attribute age @@ -150,7 +162,9 @@ and subproject
- Select the dummy relationship type and then delete it.
- Select the Employment relation and add a required attribute "salary" (type integer) -
- Go back to the admin page (/admin)
- Click on the Groups -> GuideStar.org. Add ArsDigita as a component
- Remove the composition rel type from this group
- Readd the composition rel type. Make sure arsdigita @@ -175,16 +189,21 @@ remove relation to arsdigita, then to guidestar. Remove all of these relations.
- Make yourself a project lead of guidestar again. -
- Go to /acs-admin/users and add 4 users
- Go to /admin/groups and click on "relationship to site." You should see all of the people you just entered listed as members of the subsite.
- Try to remove your Membership relation. You should see only one constraint violation.
- Remove one of the other people from the registered users group. You should be allowed to do it immediately.
- Add back the person you removed.
- Remove yourself from the registered users group. Make yourself a project lead on guidestar again.
- Make another user a project lead on guidestar. -
- Go to /admin/group-types
- Select the project group type
- Delete this group type. Should get prompted to delete sub projects group type.
- Delete the sub projects group type.
- Should get prompt to delete the project lead rel type
- Delete the project lead rel type. Continue until you @@ -197,9 +216,11 @@ drop package developer_defined_test_type; -
- ACS administrator directory (/admin/groups for each subsite)
- Tcl script directory
- PL/SQL packages
- Requirements document
- Acceptance test -
- Groups were given no context
- Groups could not be deleted
- Group types could not be created
- Relationships were limited to membership and composition, not including subtypes of these two.
- We create the ACS object type
- We create a table to store the attributes for the new type
- We create a PL/SQL package with a new function and delete procedure
- "Create Group Types" (Boolean). Determines whether new group types can be created dynamically.
- "Create Relationship Types" (Boolean). Determines whether new relationship types can be created dynamically. -
- System owner: mbryzek\@arsdigita.com
- Documentation author mbryzek\@arsdigita.com -
- 10.10 Default relationship types for group types
Each group type should specify a set of permissible relationship types to use for groups of that type.
- 10.20 Default relationship types for groups
The administrator must be able to specify the permissible relationship types to use for each group. The defaults are inherited from the list of permissible relationship types for the group's type.
-- 20.10 Define a new group type
Users should be able to create a new type of group.
- 30.10 Specify attributes
Users should be able to dynamically add attributes to group types. These attributes should be stored @@ -78,7 +96,9 @@ given relationship type to the list of allowable relationship types to apply to a given group or group type. Any subtype of an allowable relationship type will also be allowed.
-- 100.10 Create a group type with attributes
When creating a new group type, the UI should support ACS @@ -102,8 +122,10 @@ 130.10.20 Delete group type
Allow administrators to delete the group type. This action removes all groups of this type.
- -150.10 Group instance summary page
- +150.10 Group instance summary page
- 150.10.10 Display relations
Each group should display all the parties related to it and through what relationship type. Offer links to remove each @@ -119,7 +141,9 @@ relationship type. The UI must also integrate with the relational constraints data model to support defining constraints on intra-party relations.
-- User directory -- none;
wwwexists only for documentation. - ACS administrator directory -- none.
- Subsite administrator directory -- none.
-
Tcl script directory. Almost no
@@ -17,7 +18,9 @@
system at all. There's the one table
ad_template_sample_usersthat some of the demonstrations use. - Requirements document
- ER diagram -- none.
- Transaction flow diagram -- none. -
-
What this package is intended to allow the user to
accomplish.
The overall goal of the templating system is to provide the @@ -88,7 +91,9 @@ master template.
- Performance (high): Early versions of the templating system were a compuational burden. This has been fixed. Thanks to compilation of .adp pages and caching of both .adp and .tcl parts @@ -159,13 +169,20 @@ format mass mailings (spam), and any other formal (e.g., XML) could be used.
- Testability(low): A demonstration sample page exercises most mechanisms of the templating system. -
- onevalue (string)
- onerow
- multirow
- onelist
- multilist -
- The HTML is streamed to the client by the handler.
- System creator: Karl Goldstein
- System owners: Karl @@ -267,7 +307,9 @@ Goldstein, Christian Brechbühler, and Bryan Quinn -
- 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). -
First and last items may be formatted differently from items in between.
Special breaks may be required when a particular value changes. For example, a query may return the name and office of all employees in a company, and the designer may wish to insert a subheading for each office.
Colors or patterns may alternate between items. For example, the designer may want to have alternate between white and gray bands in a table.
-Template tags are processed by the server each time a page is requested. The end result of this processing is a standard HTML page that is delivered to the user. Users do not see template tags @@ -87,7 +116,9 @@ Specifically, if you must use the
<% %>tag, do not callns_puts, because it will not work the same way as in AOLserver's ADP pages.
-- User Guide
- Overview
- Establishing data sources
-
@@ -52,13 +57,17 @@
in memory
-- 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. -
A common solution. Programmers and designers should only have to learn a single system that serves as a UI substrate for all @@ -43,5 +43,6 @@ maintaining code on the server. HTML authors should be able to access information about template specifications and work on templates remotely without needing shell access to the server.
-- Do not write to the connection directly. Avoid
ns_puts,ns_writeetc., which don't wait till the headers are written or the page is completed; they may act @@ -41,14 +50,19 @@ - I use the general
<if>construct to handle @@ -326,13 +346,15 @@ optionalif_no_rowsblock, just likedb_foreach. They aren't used in the example, though.
- - Add ;noquote to the "HTML component" variables noted in the previous step. + After that, test that the template behaves as it should, and you're done.
- A set of custom markup tags (using ADP, AOLserver Dynamic @@ -38,7 +48,10 @@ the layout (from a layout template) into a single dynamically generated HTML page.
- A mechanism for specifying a single master template to be used for multiple pages. -
- 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 @@ -65,16 +81,23 @@ notation will generally take the form of some kind extended HTML.
- A mechanism for communicating the data sources and page properties from the logic part of the page -
- Design document
- Design document
-
10.0 A Common Solution
Programmers and designers should only have to learn a single system that serves as a UI substrate for all the functionally @@ -172,7 +195,10 @@ template specifications and work on templates remotely without needing shell access to the server.
- -
100.0 Distribution
The Templating System must be releasable as part of the ACS and as a separate product. When distributed as part of the ACS all @@ -185,7 +211,9 @@ page load speed by more than 10% versus a Tcl page with inline HTML.
- -
110.0 Performance
The Templating System must not cause any performance problems to a site. It must be fast and efficient, and it must not slow down page load speed by more than 10% versus a Tcl page with inline HTML.
- chain-frac-0, a Tcl page with inline HTML,
-
@@ -26,25 +31,29 @@
chain-frac-2,
an ADP page that simply
<include>s chain-frac-1.
- - Extract time from log file sections. This is done in tcsh. @@ -162,4 +173,3 @@ Last modified: Tue Oct 17 20:11:49 EDT 2000
XI. Authors
+XII. Revision History
+ +
+XII. Revision History
+
- Index: openacs-4/packages/acs-events/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-events/www/doc/index.adp,v diff -u -N -r1.2.2.2 -r1.2.2.3 --- openacs-4/packages/acs-events/www/doc/index.adp 21 Aug 2015 10:28:44 -0000 1.2.2.2 +++ openacs-4/packages/acs-events/www/doc/index.adp 25 Aug 2015 18:02:07 -0000 1.2.2.3 @@ -2,10 +2,14 @@Document Revision # Action Taken, Notes When? By Whom? 0.1 Creation 11/20/2000 W. Scott Meeks {/doc/acs-events {ACS Events}} {ACS Events Documentation} ACS Events Documentation - - ACS Events Documentation
-by wsmeeks\@arsdigita.comEngineering Docs
-
+
+by wsmeeks\@arsdigita.com
+
Engineering Docs
+Release Notes
Please file bugs in the Bug Tracker.
Release Notes
+Please file bugs in the Bug Tracker.
+
+wsmeeks\@arsdigita.com Index: openacs-4/packages/acs-events/www/doc/requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-events/www/doc/requirements.adp,v diff -u -N -r1.2.2.6 -r1.2.2.7 --- openacs-4/packages/acs-events/www/doc/requirements.adp 21 Aug 2015 10:49:20 -0000 1.2.2.6 +++ openacs-4/packages/acs-events/www/doc/requirements.adp 25 Aug 2015 18:02:07 -0000 1.2.2.7 @@ -2,34 +2,40 @@{/doc/acs-events {ACS Events}} {ACS Events Service Requirements} ACS Events Service Requirements - - ACS Events Service Requirements
+ by W. Scott Meeks -I. Introduction
This document records the requirements for a new ACS Events +
I. Introduction
+This document records the requirements for a new ACS Events service package. This package is intended to provide basic functionality which can be used in a consistent manner by other service and application packages. The events service specifies relationships (possibly recurring) between a set of time intervals time, an activity, and an arbitrary number of parties. An activity -can be associated with an arbitrary number of ACS objects.
II. Vision Statement
The ACS Events package will provide support for other services +can be associated with an arbitrary number of ACS objects.
+II. Vision Statement
+The ACS Events package will provide support for other services and applications that require representing this sort of relationship between time, parties, activities, and objects. Such applications include the generation of calendar objects, room -reservations, event registration, and possibly workflow.
The service needs to support recurring events. Many applications +reservations, event registration, and possibly workflow.
+The service needs to support recurring events. Many applications need to represent blocks of time within a given day that are intended to be be repeated regularly on subsequent days. The service should support representing the most common types of recurrences: daily, weekly, monthly, et cetera. It should also -provide for custom recurrences.
Having a single service for this functionality provides a number -of business advantages:
-
+provide for custom recurrences.
+
Having a single service for this functionality provides a number +of business advantages:
+For example, the events service could support a room reservation +
For example, the events service could support a room reservation application that is integrated with an application which maintains users's personal and group calendars. Suppose Stephanie uses the room reservation application to reserve the Boston 1st floor @@ -40,23 +46,33 @@ calendar item to appear on Ern, Allen, and Alan's calendars, the reservation application can simply pass the event to the calendar application which adds a mapping between the activity and a new -calendar item.
III. ACS Events Package Overview
There are four main areas of functionality in the events +calendar item.
+III. ACS Events Package Overview
+There are four main areas of functionality in the events package: events, time intervals, activities, and recurrences. The -service depends upon the ACS object and parties systems.
III.A Events
An event is an activity associated with a temporal +service depends upon the ACS object and parties systems.
+III.A Events
+An event is an activity associated with a temporal interval or several such intervals. Events may have additional attributes as well. Examples of events include: "hitchhiking from 4pm to 5pm", "attending the InSync concert from 11pm to 1am at the Enormodome", et cetera. Events are represented by designating the associated activity together with a set of time intervals -indicating when that activity is to occur.
An event can optionally be mapped to a set of parties +indicating when that activity is to occur.
+An event can optionally be mapped to a set of parties representing groups or individuals that have some connection to the -event.
The service provides an API for manipulating events.
An event is a relationship which maps parties and an activity to +event.
+The service provides an API for manipulating events.
+An event is a relationship which maps parties and an activity to a set of time intervals. The relationship between a particular event can be one to many with parties. Time intervals can be open -ended.
Activities contain a name, a description, and an optional link +ended.
+Activities contain a name, a description, and an optional link to related information. Ativites can be mapped one to many to ACS objects. The object mapped to a particular activity can be another -activity or event.
III.B Time Interval Sets
A time interval set is a range of moments at which an event can +activity or event.
+III.B Time Interval Sets
+A time interval set is a range of moments at which an event can occur. A single time interval is of the form "from 3:00pm to 3:17pm on 11/20/2000". A time interval set is of the form "from 3:00pm to 3:17pm and from 4:30pm to 4:45pm on 11/20/2000". A set of time @@ -65,166 +81,243 @@ and pick up again the next, and (ii) if implemented properly, it allows a simplification of the above account of events, as now an event can be identified with a pair of an activity together with a -time interval set.
The service provides an API for manipulating time interval -sets.
III.C Activities
An activity is a thing that a person or people do, +time interval set.
+The service provides an API for manipulating time interval +sets.
+III.C Activities
+An activity is a thing that a person or people do, usually represented by a gerundic phrase, such as "biking", "reserving a room", "travelling to Bhutan to achieve enlightenment", et cetera. Activities are represented via a name and a description. An activity can optionally be mapped to a set of ACS objects.
+ The service provides an API for manipulating activities. -III.D Recurring Events
Consider an event, say, an activity A performed on day D at time +
III.D Recurring Events
+Consider an event, say, an activity A performed on day D at time T. The ACS Events service allows applications to generate new events which are the same activity A performed on different days in the future, but at the same time of day T; such events are said to be recurrences of the primary event. Recurrences can happen on a daily, weekly, monthly, yearly or custom basis. The start and -end dates of recurrences can be uniformly offset.
III.E Dependencies
The service depends on the ACS object model and on our parties +end dates of recurrences can be uniformly offset.
+III.E Dependencies
+The service depends on the ACS object model and on our parties system. Event is a subtype of acs_object. The ACS Events service maps between the event object, a time interval set, an activity, -and an arbitrary number of parties.
IV. Use-cases and User-scenarios
Determine the types or classes of users who would use the +and an arbitrary number of parties.
+IV. Use-cases and User-scenarios
+Determine the types or classes of users who would use the system, and what their experience would be like at a high-level. Sketch what their experience would be like and what actions they -would take, and how the system would support them.
V. Related Links
-
+would take, and how the system would support them.
+
V. Related Links
+VI.A Data Model Requirements
10.10 Events
+
VI.A Data Model Requirements
+10.10 Events
+10.10.10 The data model represents activities associated -with sets of time intervals.
+with sets of time intervals.
+10.10.20 Events can optionally be associated with -parties.
-10.10.30> Events can optionally recur.
10.20 Time Interval Sets
+parties.
++10.10.30> Events can optionally recur.
+10.20 Time Interval Sets
+10.20.10 A time interval consists of a start time and an -end time.
+end time.
+10.20.20 A time interval set consists of a set of -associated time intervals.
+associated time intervals.
+10.20.30 Individual time intervals can be open ended. That is, the beginning time, ending time, or both may be null. The exact meaning of a null time is application dependent. However, as a suggestion, null end time could indicate events such as holidays or birthdays that have no particular start time associated with them. Null start time could indicate a due date. Both times null could indicate some item that needs to be scheduled in the future -but does not yet have a set time.
10.30 Activities
-10.30.10 An activity has a name and a description.
+but does not yet have a set time.
+10.30 Activities
++10.30.10 An activity has a name and a description.
+10.30.20 An activity can be associated with a set of ACS -objects.
+objects.
+10.30.30 An event object can be a valid target for an activity. This could indicate time dependencies, e.g. for workflow -or project management.
10.50 Recurring Events
+or project management.
+10.50 Recurring Events
+10.50.10 The data model provides a table which describes -how to generate recurrences from a base event.
10.50.20 Recurring on a daily basis should be supported. +how to generate recurrences from a base event. +10.50.20 + Recurring on a daily basis should be supported.10.50.30 Recurring on a weekly basis should be supported. For weekly recurrences, it should be possible to specify exactly -which days of the week.
+which days of the week.
+10.50.40 Recurring every month on a particular date -should be supported.
+should be supported.
+10.50.50 Recurring every month on a particular day of a -particular week should be supported.
+particular week should be supported.
+10.50.60 If a date in the 4th or 5th week of a month has been selected, then an option should be presented allowing an item -to recur on a particular day of the last week of a month.
+to recur on a particular day of the last week of a month.
+10.50.70 Recurring yearly on a particular date should be -supported.
+supported.
+10.50.80 The data model should allow an application to -provide a custom recurrence function.
+provide a custom recurrence function.
+10.50.90 It should be possible to specify an end date for -recurrences.
+recurrences.
+10.50.100 It should be possible to specify no end date -for recurrences.
+for recurrences.
+10.50.110 The service should enforce reasonable limits on the amount of data used to represent recurring events. In other words, it should not be possible to fill the DB with thousands of rows representing a single recurring event, even if it recurs -indefinitely.
+indefinitely.
+10.50.120 The service should provide a view for querying -on those recurrences that aren't fully populated in the DB.
VI.B API Requirements
20.10 Event API
-20.10.10 The service supports adding an event.
+on those recurrences that aren't fully populated in the DB.
+VI.B API Requirements
+20.10 Event API
++20.10.10 The service supports adding an event.
+20.10.15 The service supports setting the time interval -set of an event.
+set of an event.
+20.10.20 The service supports setting the activity of an -event.
+event.
+20.10.30 The service supports adding or deleting a party -mapping to an event.
+mapping to an event.
+20.10.40 The service supports deleting a complete -event.
20.20 Time Interval Set API
+event.
+20.20 Time Interval Set API
+20.20.10 The service supports adding a time interval -set.
+set.
+20.20.20 The service supports adding a time interval to a -set.
+set.
+20.20.30 The service supports updating the start or end -dates of a time interval.
+dates of a time interval.
+20.20.40 The service supports deleting a time interval -from a set.
+from a set.
+20.20.50 The service supports counting the number of time -intervals in a set.
+intervals in a set.
+20.20.60 The service supports determining if a given -interval overlaps a particular time interval set.
20.30 Activity API
-20.30.10 The service supports creating an activity.
-20.30.20 The service supports deleting an activity.
+interval overlaps a particular time interval set.
+20.30 Activity API
++20.30.10 The service supports creating an activity.
++20.30.20 The service supports deleting an activity.
+20.30.30 The service supports updating the name of an -activity.
+activity.
+20.30.40 The service supports updating the description of -an activity.
+an activity.
+20.30.50 The service supports adding or deleting an -object mapping to an event.
20.50 Recurrence API
+object mapping to an event.
+20.50 Recurrence API
+20.50.10 The service supports adding recurrences of an -event.
+event.
+20.50.20 The service supports deleting recurrences of an -event.
+event.
+20.50.30 The service supports uniformly offsetting the start or end times of time intervals of recurrences of an -event.
+event.
+20.50.40 The service supports determining if an event -recurs.
VII. Design and Implementation Notes
VII.A 3.4 Calendar Package
The 3.4 +recurs.
+VII. Design and Implementation Notes
+VII.A 3.4 Calendar Package
+The 3.4 calendar package provides some ideas for the design and implementation of the events service. One way to look at the service is as a distillation of the components of the calendar data model and implementation which would be common to any event-based application. In particular, I anticipate the table for recurring information will be very similar to the calendar data model for -recurring items.
VII.B Problem Set 2
Another way to look at this events service is as an elaboration +recurring items.
+VII.B Problem Set 2
+Another way to look at this events service is as an elaboration of the scheduling service in Problem Set 2 revised for ACS 4.0. The main differences are allowing multiple time intervals, and a one to many relationship with parties and objects. Thus the data model will have the core event_id, and repeat_id in the event subtype of acs_object. Time Intervals will be in a separate table. The parties column and object column will -be split out into separate mapping tables.
VII.C Recurring Events
There is a very important tradeoff to be made in the +be split out into separate mapping tables.
+VII.C Recurring Events
+There is a very important tradeoff to be made in the implementation of recurring events. Calendar Design Tradeoffs details this tradeoff as applied to the 3.4 -calendar package.
There are two main choices for supporting recurring events. One +calendar package.
+There are two main choices for supporting recurring events. One choice is to insert only a single row for each recurring event, regardless of the number of times it will recur. This row contains all the information necessary to compute whether or not that event would recur on a particular day. The alternative is to insert a row -for each recurrence.
I favor the second approach for the following reasons. First, +for each recurrence.
+I favor the second approach for the following reasons. First, one tradeoff is time vs. space. Computation, particularly if it might need to be done in Tcl and not solely in the database, is relatively expensive compared to storing additional information in the database. In many cases, the only information that will need to be stored for recurrences is the date and time of the -recurrence.
Another reason is that the first approach, to insert only a +recurrence.
+Another reason is that the first approach, to insert only a single row, seems to require a significantly more complex design. Thus the design, implementation and eventual maintenance time would -be greater.
This approach will also make it much easier to handle exceptions +be greater.
+This approach will also make it much easier to handle exceptions to recurrences and individualizing the objects associated with -instances of events.
However, there are drawbacks to this approach. First, it will be +instances of events.
+However, there are drawbacks to this approach. First, it will be more difficult to handle events that recur indefinitely. Second (but related) is that safeguards will need to be put in place to prevent pathological (accidental or intentional) cases from -swamping the database.
Another issue is that when populating the DB with recurring +swamping the database.
+Another issue is that when populating the DB with recurring event instances, there is an application-level choice that the service needs to support. This is the decision as to whether the new event instances are mapped to the same object or to newly created objects. For example, for the reservation application, the instances should be mapped to the same room object. Alternately, for the calendar application, the instances should be mapped to new calendar events so that each instance can be modified -individually.
VIII. Revision History
+individually. +
+VIII. Revision History
+Document Revision # Action Taken, Notes When? By Whom? @@ -243,6 +336,8 @@ 0.6 Clean up, clarification, rewording 12/08/2000 Joshua Finkler
smeeks\@arsdigita.com +
+smeeks\@arsdigita.com + Last modified: $Date$ - 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 -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/acs-lang/www/doc/i18n-design.adp 20 Aug 2015 17:43:22 -0000 1.1.2.1 +++ openacs-4/packages/acs-lang/www/doc/i18n-design.adp 25 Aug 2015 18:02:07 -0000 1.1.2.2 @@ -2,16 +2,20 @@{/doc/acs-lang {Localization}} {ACS 4 Globalization Detailed Design} ACS 4 Globalization Detailed Design - - ACS 4 Globalization Detailed Design
+ by Henry MinskyI. Essentials
+ When applicable, each of the following items should receive its own link:II. Introduction
III. Historical Considerations
V. Design Tradeoffs
-
+
II. Introduction
+III. Historical Considerations
+V. Design Tradeoffs
+VI. API
VI.A Locale API
10.30 A Locale object represents a specific geographical, + +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 @@ -45,27 +54,36 @@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 +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 +
+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:
+ +
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 +"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.@@ -77,32 +95,44 @@+ 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 +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 asContent-Type: text/html; charset=iso-8859-1 -
You can obtain the preferred character set for a locale via the -ad_locale API shown below:
+
+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:
+name to a Tcl encoding name: +
+[ns_encodingforcharset "iso-8859-1"] => iso8859-1 -
Templating
+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:
-
+following ways:
+
Caching multilingual ADP Templates
+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 +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:
++ +
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 + +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 +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 +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:
++filename.locale_or_language.adp. +
Examples:
+foo.en_US.adp foo.en.adp @@ -171,13 +217,16 @@ foo.ja_JP.adp foo.ja.adp -
The user request has a locale which is of the form +
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:
-
+"en_US".
+
The algorithm for finding the best matching template for a +request in a given locale is given below:
+Once a template file is found we must decide what character set +
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 +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 +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 +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 +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
+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 +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:
++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} @@ -258,24 +320,31 @@ ns_param HttpOpenCharset shift_jis ns_param DefaultCharset shift_jis -VI.A Message Catalog API
+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 +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:
+follows: +
+
+ The locale arg can actually be a full locale, or else a simple -language abbrev, such as fr, en, etc. The lookup +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_lookuplocalekey [default_string]
lang_message_lookupis abbreviated by the procedure named "_", which is the convention used by the GNU strings message catalog package.-
@@ -285,8 +354,10 @@
prefix.
[lang_message_lookup $locale notes.title "Title"] @@ -298,29 +369,39 @@ [_ $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 + +(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:
+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. +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 +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:@@ -329,6 +410,7 @@ bboard.shift_jis bboard.iso-8859-6+ A message catalog file consists of tcl code to define messages in a given language or locale:@@ -338,19 +420,27 @@ ...
+ In the example above, if the catalog file was loaded from the bboard package, all of the keys would be prefixed autmatically with -"bboard.". +"bboard.+".Loading A Message Catalog At Package Init Time
+ The API functionlang_catalog_loadpackage_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 +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 @@ -360,26 +450,33 @@ /other.iso8859-1.cat /other.shift_jis.cat /other.iso-8859-6.cat -You can add more pseudo-levels of hierarchy in naming the +
You can add more pseudo-levels of hierarchy in naming the message keys, using any separator character you want, for -example
+example +
-
+ which will be stored with the full key of -bboard.alerts.mail_notification. +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 +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 @@ -438,15 +535,19 @@ <trn key="hello" static>Hello</trn>
VII. Data Model Discussion
Internationalizing the Data Models
+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:
+another language: +
user groups: group_name @@ -482,14 +583,20 @@ 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. +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
+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. @@ -498,7 +605,11 @@ 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
-
+table.
+
VIII. User Interface
+IX. Configuration/Parameters
+X. Code Examples
+XI. Future Improvements/Areas of Likely Change
XII. Authors
-
+
XI. Future Improvements/Areas of Likely Change
+XII. Authors
+XII. Revision History
The revision history table below is for this template - -modify it as needed for your actual design document.
+ +
+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? @@ -538,5 +655,7 @@ -0.4 Definition of effective locale for template caching, documentation of TRN tag 12/12/2000 Henry Minsky
hqm\@arsdigita.com
- +
+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 -N -r1.1.2.6 -r1.1.2.7 --- openacs-4/packages/acs-lang/www/doc/i18n-requirements.adp 21 Aug 2015 10:49:20 -0000 1.1.2.6 +++ openacs-4/packages/acs-lang/www/doc/i18n-requirements.adp 25 Aug 2015 18:02:07 -0000 1.1.2.7 @@ -2,15 +2,17 @@{/doc/acs-lang {Localization}} {ACS 4 Globalization Requirements} ACS 4 Globalization Requirements + ACS 4 Globalization Requirements
+by Henry Minsky, Yon Feldman, Lars Pind, others
+I. Introduction
- -ACS 4 Globalization Requirements
by Henry Minsky, Yon Feldman, Lars Pind, others
I. Introduction
This document describes the requirements for functionality in the ACS platform to support globalization of the core and optional modules. The goal is to make it possible to support delivery of applications which work properly in multiple locales with the lowest development and maintenance cost. -Definitions
+
+Definitions
+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
The definition of the subset of a user's environment that @@ -19,27 +21,35 @@ customs and coded character sets.
globalization
A product development approach which ensures that software products are usable in the worldwide markets through a combination of internationalization and localization.
-II. Vision Statement
+II. Vision Statement
+ The Mozilla project suggests keeping two catchy phrases in mind when thinking about globalization:Building an application often involves making a number of +
Building an application often involves making a number of assumptions on the part of the developers which depend on their own culture. These include constant strings in the user interface and system error messages, names of countries, cities, order of given and family names for people, syntax of numeric and date strings and -collation order of strings.
The ACS should be able to operate in languages and regions +collation order of strings.
+The ACS should be able to operate in languages and regions beyond US English. The goal of ACS Globalization is to provide a clean and efficient way to factor out the locale dependent functionality from our applications, in order to be able to easily -swap in alternate localizations.
This in turn will reduce redundant, costly, and error prone +swap in alternate localizations.
+This in turn will reduce redundant, costly, and error prone rework when targeting the toolkit or applications built with the -toolkit to another locale.
The cost of porting the ACS to another locale without some kind +toolkit to another locale.
+The cost of porting the ACS to another locale without some kind of globalization support would be large and ongoing, since without a mechanism to incorporate the locale-specific changes cleanly back into the code base, it would require making a new fork of the -source code for each locale.
III. System/Application Overview
+source code for each locale. +III. System/Application Overview
+ A globalized application will perform some or all of the following steps to handle a page request for a specific locale:-
@@ -60,15 +70,19 @@
time, numeric, currency). If templating is being used, this may be
done either before and/or after merging the data with a
template.
-
Since the internationalization APIs may potentially be used on + +
Since the internationalization APIs may potentially be used on every page in an application, the overhead for adding internationalization to a module or application must not cause a -significant time delay in handling page requests.
In many cases there are facilities in Oracle to perform various +significant time delay in handling page requests.
+In many cases there are facilities in Oracle to perform various localization functions, and also there are facilities in Java which we will want to move to. So the design to meet the requirements will tend to rely on these capabilities, or close approximations to them where possible, in order to make it easier to maintain Tcl and -Java ACS versions.
IV. Use-cases and User-scenarios
+Java ACS versions. +IV. Use-cases and User-scenarios
+ Here are the cases that we need to be able to handle efficiently:Competitive Analysis
Other application servers: ATG Dyanmo, Broadvision, Vignette, -... ? Anyone know how they deal with i18n ?
V. Related Links
-
+
+
Competitive Analysis
+Other application servers: ATG Dyanmo, Broadvision, Vignette, +... ? Anyone know how they deal with i18n ?
+V. Related Links
+VI Requirements
+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 +VI.A Locales
+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. @@ -127,7 +149,10 @@ 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 + +VI.B Associating a Locale with a Request
+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 @@ -142,7 +167,10 @@ request locale from thead_connstructure. -VI.C Resource Bundles / Content Repository
30.0 A mechanism must be provided for a developer to group a + +VI.C Resource Bundles / Content Repository
+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 @@ -151,11 +179,15 @@ themselves are locale-specific, such as images of English or Japanese text (as on www.arsdigita.com). It should be easy to specify alternate configurations of text and graphics to lay out -the page for different locales.
Design note: Alternative mechanisms to implement this +the page for different locales.
+Design note: Alternative mechanisms to implement this functionality might include using templates, Java ResourceBundles, content-item containers in the Content Repository, or some 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 +catalog. +VI.D Message Catalog for String Translation
+40.0 + A message catalog facility will provide a database of translations for constant strings for multilingual applications. It must support the following:@@ -194,33 +226,42 @@ caching for performance? Would we get a nice user interface and version control almost for free? -
VI.E Character Set Encoding
Character Sets+ +
VI.E Character Set Encoding
+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.
The assumption is that we are going to use Unicode in our +use.
+The assumption is that we are going to use Unicode in our database to hold all text data. Our current programming environments (Tcl/Oracle or Java/Oracle) operate on Unicode data internally. However, since Unicode is not yet commonly used in browsers and authoring tools, the system must be able to read and write other character sets. In particular, conversions to and from Unicode will need to be explicitly performed at the following -times:
-
+times:
+
+
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 +
+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 @@ -255,7 +296,9 @@ 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
+
+VI.F ACS Kernel Issues
+60.10 All ACS error messages must use the message catalog and the request locale to generate error message for the appropriate locale. @@ -265,7 +308,9 @@ 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
+
+VI.G Templates
+70.0 For a given abstract URL, the designer may create multiple locale-specific template files may be created (one per locale or language) @@ -297,7 +342,9 @@ 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
-VI.H Sorting and Searching
+
+VI.H Sorting and Searching
+80.10 Support API for correct collation (sorting order) on lists of strings in locale-dependent way.
@@ -308,7 +355,9 @@
ORDER BYclauses in queries.80.40 The system must handle full-text search in any supported language.
-VI.G Time Zones
+
+VI.G Time Zones
+90.10 Provide API support for specifying a time zone
@@ -326,11 +375,15 @@ 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
++
VI.H Database
+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).
VI.I Email and Messaging
+data (such as email addresses in Japanese).VI.I Email and Messaging
+ When sending an email message, just as when delivering the content in web page over an HTTP connection, it is necessary to be able to specify what character set encoding to use. @@ -341,11 +394,14 @@ 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) -Implementation Notes
+ +Implementation Notes
+ Because globalization touches many different parts of the system, we want to reduce the implementation risk by breaking the implementation into phases. -VII. Revision History
+
+VII. Revision History
+Document Revision # Action Taken, Notes When? By Whom? @@ -356,5 +412,7 @@ 0.3 comments from Christian 1/14/2000 Henry Minsky
hqm\@arsdigita.comLast modified: $Date$
- +
+hqm\@arsdigita.com +Last modified: $Date$
Index: openacs-4/packages/acs-lang/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-lang/www/doc/index.adp,v diff -u -N -r1.1.2.4 -r1.1.2.5 --- openacs-4/packages/acs-lang/www/doc/index.adp 21 Aug 2015 10:28:45 -0000 1.1.2.4 +++ openacs-4/packages/acs-lang/www/doc/index.adp 25 Aug 2015 18:02:07 -0000 1.1.2.5 @@ -2,9 +2,10 @@{/doc/acs-lang {Localization}} {ACS Localization Documentation} ACS Localization Documentation - - - ACS Localization Documentation
Engineering Documentation
-
+
ACS Localization Documentation
+Engineering Documentation
+Release Notes
Please file bugs in the Bug Tracker.
- +Release Notes
+Please file bugs in the Bug Tracker.
Index: openacs-4/packages/acs-mail-lite/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-mail-lite/www/doc/index.adp,v diff -u -N -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/acs-mail-lite/www/doc/index.adp 21 Aug 2015 10:28:45 -0000 1.1.2.2 +++ openacs-4/packages/acs-mail-lite/www/doc/index.adp 25 Aug 2015 18:02:08 -0000 1.1.2.3 @@ -2,23 +2,25 @@{/doc/acs-mail-lite {Mail Services Lite}} {User Documentation for ACS Mail Lite} User Documentation for ACS Mail Lite - - User Documentation for ACS Mail Lite
+ Acs Mail Lite handles sending of email via sendmail or smtp and includes a bounce management system for invalid email accounts.When called to send a mail, the mail will either get sent immediately or placed in an outgoing queue (changeable via -parameter) which will be processed every few minutes.
ACS Mail Lite uses either sendmail (you have to provide the +parameter) which will be processed every few minutes.
+ACS Mail Lite uses either sendmail (you have to provide the location of the binary as a parameter) or SMTP to send the mail. If the sending fails, the mail will be placed in the outgoing queue again and be given another try a few minutes later when processing -the queue again.
Each email contains an X-Envelope-From adress constructed as +the queue again.
+Each email contains an X-Envelope-From adress constructed as follows:
The adress starts with "bounce" (can be changed by a parameter) followed by the user_id, a hashkey and the package_id of the package instance that sent the email, separated by "-". The domain -name of this adress can be changed with a parameter.The system checks every 2 minutes (configurable) in a certain +name of this adress can be changed with a parameter.
+The system checks every 2 minutes (configurable) in a certain maildirectory (configurable) for newly bounced emails, so the mailsystem will have to place every mail to an address beginning with "bounce" (or whatever the appropriate parameter says) in that @@ -31,9 +33,11 @@ that particular package-key. This enables each package to deal with bouncing mails on their own - probably logging this in special tables. ACS Mail Lite then logs the event of a bounced mail of that -user.
Every day a procedure is run that checks if an email account has +user.
+Every day a procedure is run that checks if an email account has to be disabled from receiving any more mail. This is done the -following way:
-
+following way:
+
Release Notes
Please file bugs in the Bug Tracker.
- +Release Notes
+Please file bugs in the Bug Tracker.
Index: openacs-4/packages/acs-messaging/www/doc/design.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-messaging/www/doc/design.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-messaging/www/doc/design.adp 20 Aug 2015 17:19:51 -0000 1.2.2.1 +++ openacs-4/packages/acs-messaging/www/doc/design.adp 25 Aug 2015 18:02:08 -0000 1.2.2.2 @@ -2,9 +2,8 @@{/doc/acs-messaging {Messaging}} {ACS Messaging Design} ACS Messaging Design - - ACS Messaging Design
+ ACS Messaging was born out of the design of the new bboard. One thing we discovered when researching requirements for bboard and discussion software in general was that there are a variety of ways @@ -49,14 +48,17 @@ message), extensible headers (just like the webmail datamodel), and versioning as provided by the content repository.API
-ACS Messaging provides theacs_messages_allview as + +ACS Messaging provides theacs_messages_all+ view as the primary mechanism for message queries.
+ ACS Messaging provides the PL/SQL function acs_message.post to add new messages. -create or replace view acs_messages_all as select m.message_id, m.reply_to, o.context_id, r.title, r.publish_date, r.mime_type, r.content, o.creation_user ...
akk\@arsdigita.com - +
+akk\@arsdigita.com Index: openacs-4/packages/acs-messaging/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-messaging/www/doc/index.adp,v diff -u -N -r1.2.2.2 -r1.2.2.3 --- openacs-4/packages/acs-messaging/www/doc/index.adp 21 Aug 2015 10:28:45 -0000 1.2.2.2 +++ openacs-4/packages/acs-messaging/www/doc/index.adp 25 Aug 2015 18:02:08 -0000 1.2.2.3 @@ -2,11 +2,15 @@{/doc/acs-messaging {Messaging}} {ACS Messaging Documentation} ACS Messaging Documentation - - - ACS Messaging Documentation
Engineering Documentation
-
+
ACS Messaging Documentation
+Engineering Documentation
+Release Notes
Please file bugs in the Bug Tracker.
Release Notes
+Please file bugs in the Bug Tracker.
+
+Anukul +Kapoor +Last modified: Fri Aug 21 11:50:15 CEST 2015 + \ No newline at end of file Index: openacs-4/packages/acs-messaging/www/doc/requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-messaging/www/doc/requirements.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-messaging/www/doc/requirements.adp 20 Aug 2015 17:19:51 -0000 1.2.2.1 +++ openacs-4/packages/acs-messaging/www/doc/requirements.adp 25 Aug 2015 18:02:08 -0000 1.2.2.2 @@ -2,109 +2,159 @@{/doc/acs-messaging {Messaging}} {ACS Messaging Requirements} ACS Messaging Requirements - - ACS Messaging Requirements
-by Anukul Kapoor and -Pete SuThis is only a DRAFTI. Introduction
In ACS 3.x, each messaging application (e.g. bboard, general + +by Anukul Kapoor + and +Pete Su +This is only a DRAFT +
I. Introduction
+In ACS 3.x, each messaging application (e.g. bboard, general comments, spam, ticket tracker and so on) used its own specialized data model for representing and manipulating messages. ACS Messages provides a common data model and API for these applications. The -service provides the following common mechanisms:
-
+service provides the following common mechanisms:
+
II. Vision Statement
Messaging applications constitute some of the most useful forms +
II. Vision Statement
+Messaging applications constitute some of the most useful forms of web collaboration. Many of the application packages that have been developed for ACS have a messaging component. Therefore, ACS Messaging provides a standard set of abstractions for storing, sending and receiving messages through a web service. Our goal is to support a diverse group of messaging applications through a -single centralized facility.
III. System/Application Overview
The ACS Messaging package defines a data model and API for the +single centralized facility.
+III. System/Application Overview
+The ACS Messaging package defines a data model and API for the storage and retrieval of messages. While the package standarizes how messages are stored, applications may use any data model they want for higher level organization of messages into threads, forums, and so on. ACS Messaging places no organizational -constraints on client applications.
The package consists of the following components:
-
+constraints on client applications.
+
The package consists of the following components:
+IV. Use-cases and User Scenarios
ACS Messaging is generally not used directly by users, so there +
IV. Use-cases and User Scenarios
+ACS Messaging is generally not used directly by users, so there are no user interface level scenarios to consider at this point. It's possible that in the future we will want to extend the system with generic administrative user interfaces, but this is not clear -right now.
We scenarios that we should consider are the kinds of +right now.
+We scenarios that we should consider are the kinds of applications that we mean to support with this package, and what the developers of those applications would like to see in the data -model and API.
The following applications in ACS 3.x could have been -implemented using this package:
-
+model and API.
+
The following applications in ACS 3.x could have been +implemented using this package:
+Each of these applications requires a message store and each +
Each of these applications requires a message store and each defines it's own high level organization for messages whithin that -store.
-
+store.
+
The main requirement of the ACS Messages package is to support +
The main requirement of the ACS Messages package is to support this diverse set of applications with a common infrastructure. This is because all of these applications would like the following kinds -of common functionality:
-
+of common functionality:
+
V. Related Links
VI.A Requirements: Datamodel
10.0 Message Store
ACS Messages should provide a single store for objects -representing messages.
20.0 Message Content
A message should have a primary content body consisting of a +
V. Related Links
+ +VI.A Requirements: Datamodel
+10.0 Message Store
+ACS Messages should provide a single store for objects +representing messages.
+20.0 Message Content
+A message should have a primary content body consisting of a specified MIME type and a block of storage holding the content. In addition, applications may store one or more seperate revisions of -a message.
30.0 Attachments
Messages may be composed of additional attachments. Each +a message.
+30.0 Attachments
+Messages may be composed of additional attachments. Each attachment should be tagged with a MIME type to indicate what type of data is stored there. Each attachment can only be attached to a single parent message. In addition, the system must be able to -store one or more revisions of each attachment.
40.0 Unique ID
Messages should have universally unique identifiers to allow -global reference and RFC-822 compliance.
50.0 Sender
Messages should be related to the sending party.
60.0 Threading
The system model simple message threads, that is chains of +store one or more revisions of each attachment.
+40.0 Unique ID
+Messages should have universally unique identifiers to allow +global reference and RFC-822 compliance.
+50.0 Sender
+Messages should be related to the sending party.
+60.0 Threading
+The system model simple message threads, that is chains of messages that are replies to each other. If message M is a reply to some other message N, then M should be able to refer to N in a -straightforward way.
70.0 Search
Messages should be searchable as part of a site wide search. +straightforward way.
+70.0 Search
+Messages should be searchable as part of a site wide search. Therefore, the data model must integrate with the data model for -site wide search.
VI.B Requirements: API
80.0 Messages
The system should provide the following interfaces for -manipulating messages:
+site wide search. +
+VI.B Requirements: API
+80.0 Messages
+The system should provide the following interfaces for +manipulating messages:
+80.10 Creation
Applications should be able to create new messages objects.
80.20 Revisions
Applications should be able to create a new revision of a given message object.
80.30 Deletion
Applications should be able to delete a message and all of its revisions and attachments. (is this true?).
80.40 Type Checking Applications should be able to check whether or not a given object is a message.
-90.0 Message Attachments
The system should provide the following interfaces for -manipulating message attachments.
+
+90.0 Message Attachments
+The system should provide the following interfaces for +manipulating message attachments.
+90.10 Creation
Applications should be able to create new message attachments and connect to their parent object.
90.20 Revisions
Applications should be able to create a new revision of a given attachment.
90.30 MIME Types
Each attachment should have a MIME type. The system should be able in principle to deal with an arbitrary collection of MIME types, although initial implementations may be more limited.
-100.0 Messages and E-Mail
The system should provide the following interfaces for +
100.0 Messages and E-Mail
+The system should provide the following interfaces for integrating with existing E-mail systems. Note that these requirements only deal with sending mail. Our feeling that a seperate package should be implemented to deal with receiving mail that would use ACS Messages for storage of -incoming messages.
+incoming messages. +
+100.10 Sending Single Messages
The system should provide a mechanism for specifying that a message should be sent as outgoing E-mail. Outgoing messages should be queued so that the system can maintain auditing information to deal with transport failures and so on.
100.20 Sending MIME Messages
The system should be able to send messages with attachments as multipart MIME messages.
100.30 Sending Digests
The system should be able to group multiple messages together as a single e-mail digest. For example, all the messages in a single bboard thread could be sent to a user as a digest.
-VII. Revision History
+ +
+VII. Revision History
+Document Revision # Action Taken, Notes When? By Whom? 0.1 Creation 10/04/2000 Anukul Kapoor 0.2 Edited and extended for more general data model 11/07/2000 Pete Su
+
+ + Last modified: $Id: requirements.html,v 1.1.1.1 2001/03/13 22:59:26 ben Exp $ - Index: openacs-4/packages/acs-reference/www/doc/design.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-reference/www/doc/design.adp,v diff -u -N -r1.2.2.6 -r1.2.2.7 --- openacs-4/packages/acs-reference/www/doc/design.adp 21 Aug 2015 10:49:20 -0000 1.2.2.6 +++ openacs-4/packages/acs-reference/www/doc/design.adp 25 Aug 2015 18:02:08 -0000 1.2.2.7 @@ -2,39 +2,57 @@{/doc/acs-reference {ACS Reference Data}} {acs-reference Design Documentation} acs-reference Design Documentation - - - acs-reference Design Documentation
I. Introduction
Reference data services are often overlooked in the rush to get +
acs-reference Design Documentation
+I. Introduction
+Reference data services are often overlooked in the rush to get coding. Much of the code is redundant or of similarly patterned implementations. This package intends to address some common -features and needs.
II. Historical Considerations
Before the existence of acs-reference, the ACS required that you +features and needs.
+II. Historical Considerations
+Before the existence of acs-reference, the ACS required that you preload some tables in a script to get some basic reference -functionality. There were many problems with this:
-
+functionality. There were many problems with this:
+
III. Design Tradeoffs
Primary Goals
-
+
III. Design Tradeoffs
+Primary Goals
+Performance
+Performance
+ When updating the reference tables their is overhead due to the fact that the table is registered with the repository. This should rarely occur anyway as the tables are only added once. By not having the actual data itself in the acs-object system, subsequent additions and deletions to the reference tables themselves are unaffected by this overhead. -IV. API
See api-browser -
V. Data Model Discussion
The UNSPSC reference data has a data model for handling data +
IV. API
+See api-browser +
+V. Data Model Discussion
+The UNSPSC reference data has a data model for handling data revisions. An application can determine any new/revised category -based on existing, obsolete data.
VI. User Interface
Their is no end user interface. There needs to be some kind of +based on existing, obsolete data.
+VI. User Interface
+Their is no end user interface. There needs to be some kind of admin UI to report status and possibly manage updates per -requirements.
VII. Configuration/Parameters
None
VIII. Future Improvements/Areas of Likely Change
A server based update mechanism will be supported. This will +requirements.
+VII. Configuration/Parameters
+None
+VIII. Future Improvements/Areas of Likely Change
+A server based update mechanism will be supported. This will allow for tables to be updated (and preferably diffed) instead of being reloaded with a package upgrade. An interface to produce xml/csv from the reference data would be a nice service to the community (allowing legacy applications a way to import this -data).
IX. Authors
Jon Griffin
- +data). +IX. Authors
+Jon Griffin
Index: openacs-4/packages/acs-reference/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-reference/www/doc/index.adp,v diff -u -N -r1.2.2.2 -r1.2.2.3 --- openacs-4/packages/acs-reference/www/doc/index.adp 21 Aug 2015 10:28:46 -0000 1.2.2.2 +++ openacs-4/packages/acs-reference/www/doc/index.adp 25 Aug 2015 18:02:08 -0000 1.2.2.3 @@ -2,10 +2,14 @@{/doc/acs-reference {ACS Reference Data}} {ACS Reference Documentation} ACS Reference Documentation - - - ACS Reference Documentation
Engineering Documentation
-
+
ACS Reference Documentation
+Engineering Documentation
+Current docs are always at:
jongriffin.com -Release Notes
Please file bugs in the Bug Tracker.
Current docs are always at:
+
jongriffin.com +Release Notes
+Please file bugs in the Bug Tracker.
+
+jon\@jongriffin.com Index: openacs-4/packages/acs-reference/www/doc/requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-reference/www/doc/requirements.adp,v diff -u -N -r1.2.2.6 -r1.2.2.7 --- openacs-4/packages/acs-reference/www/doc/requirements.adp 21 Aug 2015 10:49:21 -0000 1.2.2.6 +++ openacs-4/packages/acs-reference/www/doc/requirements.adp 25 Aug 2015 18:02:08 -0000 1.2.2.7 @@ -2,42 +2,60 @@{/doc/acs-reference {ACS Reference Data}} {ACS Reference Requirements} ACS Reference Requirements - - - ACS Reference Requirements
by Jon Griffin -
I. Introduction
This document describes the requirements for the ACS Reference +
ACS Reference Requirements
+by Jon Griffin +
+
+I. Introduction
+This document describes the requirements for the ACS Reference service package. This package has the following primary -functions:
-
+functions:
+
II. Vision Statement
What is reference data? Simply put, it is data that doesn't +
II. Vision Statement
+What is reference data? Simply put, it is data that doesn't change very often and also in many cases comes from an external source and not from within the system itself. Many times it is created from a standards body, i.e. ISO or ANSI, and may be required for a client's -particular industrial needs.
Some examples of reference data are:
-
+particular industrial needs.
+
Some examples of reference data are:
+Historically, reference data has been looked upon by developers +
Historically, reference data has been looked upon by developers as something less important than more immediate coding needs, and so most data models simply defer the issue by treating reference data as something simple to implement. Elsewhere. The reality is that for most organizations reference data is extremely important -and also extremely difficult to manage.
This module will not only package all of a site's +and also extremely difficult to manage.
+This module will not only package all of a site's reference data in one place, it will also help manage that -data.
III. System Overview
The ACS Reference package consists of:
-
+data.
+
III. System Overview
+The ACS Reference package consists of:
+IV. Use-cases and User-Scenarios
Papi Programmer is developing a module that will use country +
IV. Use-cases and User-Scenarios
+Papi Programmer is developing a module that will use country codes as part of his table structure. Instead of creating his own table he can use the ACS Reference package and the country codes therein. If the country codes change - which does in fact happen from time to time - the ACS Reference package will maintain that -information for him.
V. Related Links
VI.A Requirements: Data Model
10.10 The package should use a table that is the master +information for him.
+V. Related Links
+ +VI.A Requirements: Data Model
+10.10 The package should use a table that is the master table for all reference tables.
10.20 The package should employ a field to show whether this data is internally derived or not.
@@ -54,9 +72,13 @@ 10.80 The package should offer a representation of discontinued datetime
10.90 The package should keep an indication of who the data -maintainer is, by user_id.VI.B Requirements: API
20.10 The package should offer a function to determine if a -particular table has expired.
The requirements below are not met by the current -implementation:
30.10 There needs to be a way to query the data source and +maintainer is, by user_id.
+VI.B Requirements: API
+20.10 The package should offer a function to determine if a +particular table has expired.
+The requirements below are not met by the current +implementation:
+30.10 There needs to be a way to query the data source and update automatically. If that isn't possible, as it won't be in many cases, the application should be able to query a master server and see if there is new data for a particular table or tables. For @@ -66,9 +88,12 @@ tables. In any case, there should be an admin page that shows current status and revisions of various data, where to find info about additional sources (if applicable), and provide a UI to -upload or import new data.
VII. Implementation Notes
The package needs to handle changes to reference data in a +upload or import new data.
+VII. Implementation Notes
+The package needs to handle changes to reference data in a graceful fashion. For example, if a country splits into two or more -countries, what should happen?
-
+countries, what should happen?
+
Note also that it is possible to have overlapping effective +
Note also that it is possible to have overlapping effective dates. This will not be implemented in the first version, but should be recognized and accomodated throughout the development process for the service package.
- Index: openacs-4/packages/acs-service-contract/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-service-contract/www/doc/index.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-service-contract/www/doc/index.adp 21 Aug 2015 10:28:46 -0000 1.2.2.1 +++ openacs-4/packages/acs-service-contract/www/doc/index.adp 25 Aug 2015 18:02:08 -0000 1.2.2.2 @@ -2,26 +2,36 @@{/doc/acs-service-contract {Service Contracts}} {ACS Service Contract Documentation} ACS Service Contract Documentation - - - ACS Service Contract Documentation
Why
To facilitate greater code reuse, application integration, and -package extensibility within the OpenACS.
To do this acs-service-contract defines an api for the creation -of interfaces and discovery of interface implementations.
Background
Most component systems are based on the use of interfaces. +
ACS Service Contract Documentation
+Why
+To facilitate greater code reuse, application integration, and +package extensibility within the OpenACS.
+To do this acs-service-contract defines an api for the creation +of interfaces and discovery of interface implementations.
+Background
+Most component systems are based on the use of interfaces. Interfaces allow components to create contracts which define their functional level of reuse and customization. It also provides the infrastructure for runtime discovery of which implemented -interfaces are available.
The ACS4 is based on a thin object system, that is primarily +interfaces are available.
+The ACS4 is based on a thin object system, that is primarily relational but the acs_objects system allows a veneer of object orientedness by providing globally unique object ids, object metadata, and bundling of data and methods as an object. While this permits a level of reuse on an object or package basis, it requires -hardcoding the unit of reuse.
ACS Service contract allows these objects and packages to also +hardcoding the unit of reuse.
+ACS Service contract allows these objects and packages to also define and register their implementation of interfaces, so the -level of reuse is defined at the contract level.
In addition ACS Service contract provides mean to dispatch +level of reuse is defined at the contract level.
+In addition ACS Service contract provides mean to dispatch method calls on an interface implementation. The dispatch means is -only available through tcl.
Interface Discovery is available programmatically as well as via -documentation through ad_proc.
The Service Contract interface specification was inspired by -WDSL, the interface specfication for web services.
Hitchiker's Guide to Service Contract Definitions
-
+only available through tcl.
+
Interface Discovery is available programmatically as well as via +documentation through ad_proc.
+The Service Contract interface specification was inspired by +WDSL, the interface specfication for web services.
+Hitchiker's Guide to Service Contract Definitions
+Usage
Design the Contract
First Off design the interface for your contract, keeping in +
Usage
+Design the Contract
+First Off design the interface for your contract, keeping in mind that all implementations need to implement it and that extension of the contract after deployment is often not practical. In other words take the time to do a little future proofing and -thinking about possible uses that you weren't planning on.
Defining Operations
Next define the logical operations that will make up your -contract
Register the Contract
with acs contracts.
Implement the Contract
FAQ
Why Does an implementation reference an interface?
This might seem a little strange since a binding is the official +thinking about possible uses that you weren't planning on.
+Defining Operations
+Next define the logical operations that will make up your +contract
+Register the Contract
+with acs contracts.
+Implement the Contract
+FAQ
+Why Does an implementation reference an interface?
+This might seem a little strange since a binding is the official reference between an implementation and an interface. However it is quite possible that an implementation for interface might exist prior to the interface being defined, ie the interface defining package is not installed. By retaining this information the interface defining package can be installed and the implementations -already installed on the system can be bound to it.
Api Reference
[for oracle please syntax replace __ with .]
Creating Message Types
creates a new contract to serve as a logical container for operations. contract_desc is a text description of the -contract.
Dispatching
+Examples
+Included in the service contract package are examples for oracle +and postgresql of a trivial contract.
+Also the search contract functions as a non-trivial core +contract used by openacs4.
+Further Reading
+Abstract Factory Pattern - GOF
+Component Systems - Clemens Syzperski
+WSDL Spec
+Release Notes
+Please file bugs in the Bug Tracker.
+Credits
+Most content was provided by Neophytos Demetriou. Most of the errors were provided by Kapil Thangavelu.
- Index: openacs-4/packages/acs-service-contract/www/doc/notes.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-service-contract/www/doc/notes.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-service-contract/www/doc/notes.adp 20 Aug 2015 17:19:51 -0000 1.2.2.1 +++ openacs-4/packages/acs-service-contract/www/doc/notes.adp 25 Aug 2015 18:02:08 -0000 1.2.2.2 @@ -3,7 +3,6 @@- ACS Service Contract Overview by Neophytos Demetriou (k2pts\@yahoo.com) and Kapil Thangavelu (k_vertigo\@yahoo.com) Goals - To increase inter-application code reuse by designating @@ -21,4 +20,3 @@ registers it with the repository. Provider - Provides an implementation of the contract. Dependant - Something that uses a contract. - Index: openacs-4/packages/acs-subsite/www/doc/group-admin-pages-acceptance-test.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-subsite/www/doc/group-admin-pages-acceptance-test.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-subsite/www/doc/group-admin-pages-acceptance-test.adp 20 Aug 2015 17:19:51 -0000 1.2.2.1 +++ openacs-4/packages/acs-subsite/www/doc/group-admin-pages-acceptance-test.adp 25 Aug 2015 18:02:09 -0000 1.2.2.2 @@ -2,13 +2,16 @@ {/doc/acs-subsite {Subsite}} {Group Admin Pages - Acceptance test} Group Admin Pages - Acceptance test - - Group Admin Pages - Acceptance -test
+test + ACS subsite docs : Group Admin Pages - -Acceptance testDEVELOPER DEFINED GROUP TYPES TEST
The first thing we have to test is developer defined group -types working in conjunction with the user defined ones.Create the following object type in SQL*Plus.
begin +Acceptance test +
+DEVELOPER DEFINED GROUP TYPES TEST
+The first thing we have to test is developer defined group +types working in conjunction with the user defined ones. +Create the following object type in SQL*Plus.
+begin acs_object_type.create_type ( supertype => 'group', object_type => 'developer_defined_test_type', @@ -87,11 +90,15 @@ / show errors --
+
GROUP TYPE PAGES BASIC FUNCTIONALITY
(Start at /admin)-
+
GROUP TYPE PAGES BASIC FUNCTIONALITY
+(Start at /admin) +DYNAMICALLY EXTENDING GROUPS
(Start at /admin/group-types/)-
+
DYNAMICALLY EXTENDING GROUPS
+(Start at /admin/group-types/) +RELATIONSHIP TYPE PAGES BASIC FUNCTIONALITY
-
+
RELATIONSHIP TYPE PAGES BASIC FUNCTIONALITY
+SEGMENTS, CONSTRAINTS AND RELATIONS
-
+
SEGMENTS, CONSTRAINTS AND RELATIONS
+Testing with more Users
Now we're going to test that the user interface remains -consistent if there are a few more users.-
+
Testing with more Users
+Now we're going to test that the user interface remains +consistent if there are a few more users. +CLEANING UP
-
+
CLEANING UP
+
Michael -Bryzek + +
+Michael +Bryzek +
$Id: group-admin-pages-acceptance-test.html,v 1.3 2003/09/30 12:10:03 mohanp Exp $ - Index: openacs-4/packages/acs-subsite/www/doc/group-admin-pages-design.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-subsite/www/doc/group-admin-pages-design.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-subsite/www/doc/group-admin-pages-design.adp 20 Aug 2015 17:19:51 -0000 1.2.2.1 +++ openacs-4/packages/acs-subsite/www/doc/group-admin-pages-design.adp 25 Aug 2015 18:02:09 -0000 1.2.2.2 @@ -2,16 +2,19 @@{/doc/acs-subsite {Subsite}} {Group Admin Pages - Design} Group Admin Pages - Design - - - Group Admin Pages - Design
ACS subsite docs : Group Admin Pages - Design -I. Essentials
-
+
Group Admin Pages - Design
+ACS subsite docs + : Group Admin Pages - Design +I. Essentials
+II. Introduction
+II. Introduction
+ The group administration packages provides a "control panel" to allow the administrator of a subsite to control the groups in use on that subsite. Administrators manage the types of groups in use @@ -20,26 +23,32 @@ relations between these groups, and modify attributes of the types and groups.III. Historical Considerations
+ Versions 4.0.x of the ACS lacked a useful group administration package for subsites. For example:IV. Design Tradeoffs
+ Whenever possible, the design of this package tries to minimize disturbance to the core ACS 4.0 data model. Instead, we focus on adding a more powerful user interface and PL/SQL API to the existing group admin pages while extending the data model only when necessary. -V. API
Permissible relationship types
+V. API
+Permissible relationship types
+ We defined the following two tables to store the relationship type used to store the permissible relationship types for group types and individual groups. Whenever a group is created using the -acs_group.newfunction, the relationship types for the +acs_group.new+ function, the relationship types for the new group are automatically copied from those allowed for its group type.@@ -70,40 +79,55 @@ constraint group_rels_group_rel_type_un unique (group_id, rel_type) ); -Dynamic subtypes of object types
+ +Dynamic subtypes of object types
+ To allow administrators to create dynamic object types (e.g. -subtypes of the object typesgroup, -membership_rel, andcomposition_rel), we +subtypes of the object typesgroup+, +membership_rel+, andcomposition_rel+), we provide a Tcl library of procedure that generate PL/SQL packages. For each dynamically created object type, we:Attributes themselves are stored using
type-specificstorage. For each new attribute, we create a column in the table dynamically created for the new object -type.To support the clean separation between programmer defined +type.
+To support the clean separation between programmer defined PL/SQL packages and automatically generated packages, we add the
dynamic_pcolumn to theacs_object_types-table.+table. +
+acs_object_types.dynamic_p char(1) default 'f' constraint acs_obj_types_dynamic_p_ck check (dynamic_p in ('t', 'f')) -Note that the
dynamic_pis still experimental -and may be removed in a future version of ACSVII. Data Model Discussion
+Note that the
+dynamic_pis still experimental +and may be removed in a future version of ACSVII. Data Model Discussion
+ ...VIII. User Interface
+ The user interface comprises entirely of administrative pages -located in the/admin/directory of the subsite +located in the/admin/+ directory of the subsite package.IX. Configuration/Parameters
+ The revised group administration pages require no new package parameters.X. Future Improvements/Areas of Likely Change
+ There are many areas for improvement to the user interface, including tighter integration with the relational segments and constraints packages. One major improvement would allow individual @@ -112,11 +136,14 @@ are not themselves objects, it is difficult to properly scope object types.We also may add a few additional package parameters -including:
-
+including:
+
XI. Authors
+XI. Authors
+ This document is primarily the result of discussions between Oumi Mehrotra and Michael Bryzek. Bryan Quinn and Rafi Schloming provided key insights early in the development process. @@ -125,15 +152,20 @@XII. Revision History
+ +
+XII. Revision History
+Document Revision # Action Taken, Notes When? By Whom? 0.1 Creation 11/30/2000 Michael Bryzek 1.0 Major Revision 1/11/2001 Michael Bryzek
Michael -Bryzek
group-admin-pages-design.html,v 1.1.4.1 2001/01/12 +
+Michael +Bryzek +
+group-admin-pages-design.html,v 1.1.4.1 2001/01/12 22:43:33 mbryzek Exp - Index: openacs-4/packages/acs-subsite/www/doc/group-admin-pages-requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-subsite/www/doc/group-admin-pages-requirements.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-subsite/www/doc/group-admin-pages-requirements.adp 20 Aug 2015 17:19:52 -0000 1.2.2.1 +++ openacs-4/packages/acs-subsite/www/doc/group-admin-pages-requirements.adp 25 Aug 2015 18:02:09 -0000 1.2.2.2 @@ -2,26 +2,34 @@{/doc/acs-subsite {Subsite}} {Group Admin Pages - Requirements} Group Admin Pages - Requirements - - - Group Admin Pages - Requirements
+Group Admin Pages - Requirements
+ ACS subsite docs : Group Admin Pages - -RequirementsI. Introduction
The subsites package offers a powerful way to create discrete +Requirements +I. Introduction
+The subsites package offers a powerful way to create discrete collections of subcommunities on top of a single ACS installation. The package must be permissions-aware for all groups, relational -segments and constraints, and relations.The subsites package must also allow administrators to +segments and constraints, and relations. +
The subsites package must also allow administrators to dynamically extend existing group and relationship types and to -define attributes for new types.
II. Vision Statement
From /doc/subsites-requirements.html:The other piece of the subsite system is a +define attributes for new types. +
+This control panel needs to treat individual groups as belonging to a single instance of a subsite. However, groups themselves are not enough. We must allow a subsite to specify its own types of groups, instances of those types (or of a type from a parent subsite), and types of relationships between those -groups.II. Vision Statement
+From /doc/subsites-requirements.html: +The other piece of the subsite system is a subsite package that provides subsite admins a "control panel" for administering their subsite. This is the same package used to provide all the community core functionality available at the "main" site which is in fact simply another -subsite.
This control panel needs to treat individual groups as +subsite.III. Historical Motivations
In the ACS 3.x architecture, many modules, e.g. portals, +groups. +III. Historical Motivations
+In the ACS 3.x architecture, many modules, e.g. portals, intranet, and bboard, created their own group types to manage different aspects of the module. While it is true that the ACS Permissioning package will replace the need for group types used @@ -30,21 +38,27 @@ restrict administrative control of their groups to administrators of the subsite. Without this ability, a user with administrative privilege of one subsite can administer all other groups in the -system.IV. Use case and User Scenarios
The Intranet ApplicationThe Intranet application may model employees in many ways. +system. +
IV. Use case and User Scenarios
+The Intranet Application +The Intranet application may model employees in many ways. Without loss of generality, we assume each employee is a "person" with an "employment relation" to a company. Figure 1 shows an outline of what the ACS Site Map may look like with several companies. Note that each company represents one instance of the -intranet application.
+intranet application. + 
Figure 1: Structure of Multiple Intranets -Note: The current version of ACS, +member information. +
Note: The current version of ACS, 4.0.1, does not treat object types as objects. This is a problem for subsites wishing to support dynamic sub-typing as name collisions are common because object types do not have context. The @@ -53,15 +67,19 @@ unique to the instance. In other words, the context of the object type is set to the subsite. We use the context here so that we can automatically maintain permissions from subsite to object -type.
VI.A Requirements: Data Model
-
+type.
VI.A Requirements: Data Model
+VI.B Requirements: API
-
+
VI.B Requirements: API
+VI.C Requirements: User Interface
-
+
VI.C Requirements: User Interface
+
--
+
Revision History
+ +
+Revision History
+Document Revision # Action Taken, Notes When? By Whom? @@ -129,7 +153,10 @@ 1.0 Final Revisions 1/11/2001 Michael Bryzek
Michael -Bryzek
$Id: group-admin-pages-requirements.html,v 1.2 +
+Michael +Bryzek +
+$Id: group-admin-pages-requirements.html,v 1.2 2001/08/11 21:31:03 ben Exp $ - Index: openacs-4/packages/acs-subsite/www/doc/images.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-subsite/www/doc/images.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-subsite/www/doc/images.adp 27 Oct 2014 16:39:58 -0000 1.2 +++ openacs-4/packages/acs-subsite/www/doc/images.adp 25 Aug 2015 18:02:09 -0000 1.2.2.1 @@ -2,9 +2,8 @@{/doc/acs-subsite {Subsite}} {ACS Subsite Documentation} ACS Subsite Documentation - - Images available from the acs-subsite package
+ Image can be included with a link of the form <img src="/resources/acs-subsite/FILENAME\" />@@ -134,4 +133,3 @@
- Index: openacs-4/packages/acs-subsite/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-subsite/www/doc/index.adp,v diff -u -N -r1.2.2.3 -r1.2.2.4 --- openacs-4/packages/acs-subsite/www/doc/index.adp 21 Aug 2015 10:49:21 -0000 1.2.2.3 +++ openacs-4/packages/acs-subsite/www/doc/index.adp 25 Aug 2015 18:02:09 -0000 1.2.2.4 @@ -2,11 +2,11 @@
ZoomOut24.gif {/doc/acs-subsite {Subsite}} {ACS Subsite Documentation} ACS Subsite Documentation - - ACS Subsite Documentation
+ ACS subsite docs -Document overview
+
+Document overview
+Overall requirements Overview of the requirements that motivated the design of @@ -26,7 +26,13 @@ Subsite images Shows all (hopefully) images available from the subsite package Release Notes
Please file bugs in the Bug Tracker.
Michael -Bryzek
$Id: index.html,v 1.3.2.1 2015/08/21 10:28:47 -gustafn Exp $ - +Release Notes
+Please file bugs in the Bug Tracker.
+
+Michael +Bryzek +
+$Id: index.html,v 1.3.2.2 2015/08/21 10:49:21 +gustafn Exp $ + \ No newline at end of file Index: openacs-4/packages/acs-templating/www/doc/design.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/design.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-templating/www/doc/design.adp 20 Aug 2015 17:19:52 -0000 1.2.2.1 +++ openacs-4/packages/acs-templating/www/doc/design.adp 25 Aug 2015 18:02:09 -0000 1.2.2.2 @@ -2,12 +2,13 @@{/doc/acs-templating {Templating}} {Template System} Template System - - The Template System -- Design Document
-by Christian Brechbühler Templating System : + +by Christian Brechbühler Templating System + : Design -I. Essentials
-
+
I. Essentials
+II. Introduction
-
+
II. Introduction
+III. Historical Considerations
Karl Goldstein designed the templating system. First it was + +
III. Historical Considerations
+Karl Goldstein designed the templating system. First it was called "Karl's Templates" or "The New Templating System" to distinguish it from the obsolescent templates or "Styles" by Philip Greenspun. An extended and improved version was named "Dynamic @@ -104,11 +109,14 @@ Both these packages are now merged and appear as
acs-templatingstarting in ACS 4.0. The architecture of the package was changed several times to meet the emerging -coding/style constraints of ACS 4.0.V. Design Tradeoffs
As indicated above, the primary attribute that the page tries to +coding/style constraints of ACS 4.0.
+V. Design Tradeoffs
+As indicated above, the primary attribute that the page tries to achieve is the separation of code and layout. The primary sacrifice is simplicity; in the typical case there will be two files (a .adp templage and a .tcl script) instead of a single -.tcl page.
+.tcl page.
+Management of data sources. Through the various past versions of the package, it evolved that data sources should be set as Tcl variables and arrays. Earlier they were kept as lists @@ -124,9 +132,11 @@ and
uplevel, which is considered confusing and error-prone by reviewers (of 4.0). The use of these constructs has been reduced in 4.01, and the code is clearer -now.Other attributes are affected as follows. In parentheses the +now.
+Other attributes are affected as follows. In parentheses the estimated priorities are listed, not the degree to which -the attributes are being achieved:
-
+the attributes are being achieved:
+
VI. API
Details are in the developer +
VI. API
+Details are in the developer guide. Here we give an overview, and then the more obscure -aspects of the current implementation.
The most important abstraction is the data source, of which -there are several kinds:
-
+aspects of the current implementation.
+
The most important abstraction is the data source, of which +there are several kinds:
+Currently
ad_page_contractdoes not allow -specifying the latter two.Process Flow
+Currently
+ad_page_contractdoes not allow +specifying the latter two.Process Flow
+ In a simple case, the following is the sequence of steps that serving a templated page involves.-
@@ -180,13 +197,18 @@
interpreted and the data sources from the .tcl script are
interpolated into the template.
<include>and -<master>tags. In these cases, Tcl and/or ADP +requested with the<include>+ and +<master>+ tags. In these cases, Tcl and/or ADP parsing happens recursively. -Tcl Call Stack
Below is a diagram of the typical call stack when processing a +
Tcl Call Stack
+Below is a diagram of the typical call stack when processing a page without dependent pages. To conform to the Tcl notion of -what's up and down (as in upvar), the stack grows down.
++what's up and down (as in upvar), the stack grows down. +
Level Procedure Arguments @@ -204,45 +226,58 @@ #5 template::code::tcl::/web/service/www/page Levels #1 to #3 exposed here are request processor internals. In +
Levels #1 to #3 exposed here are request processor internals. In the case shown, datasources reside in level #5. Due to the
uplevelcommand, the frame of the sixth procedure is not accessible in the call stack at this moment, and the seventh runs in stack frame #5. If the<include>or<master>tags are used,adp_parsewill be invoked recursively. Datasources always reside in the stack -frame of an instance ofadp_parse.To keep track of data sources of several page components, the +frame of an instance of
+adp_parse.To keep track of data sources of several page components, the templating system maintains a stack of their stack levels in the variable
template::parse_level. In our case, it just contains 5. But if this page included another page or designated is as its master, the level of the nextadp_parsewould be pushed to the list, and popped when that proc returned. This next level will appear as #6, due to the repeated -upleveling.Caching and Template Compilation
To improve performance, adp pages are compiled into a tcl proc, +
+upleveling.Caching and Template Compilation
+To improve performance, adp pages are compiled into a tcl proc, and thus cached for future use. Tcl pages are also cached in a proc; this saves the trouble of reading and parsing the file the next time. The template system remembers the modification times of the adp and tcl sources, and re-processes any requested file if the cached version is no longer current. Consequently, this cacheing is -transparent in normal use.
To emphasize that "normal" use essentially always applies, +transparent in normal use.
+To emphasize that "normal" use essentially always applies, here's a scenario for abnormal use: Save version n of a file at 11:36:05.1; request a page that uses it at 11:36:05.3; modify and save version n+1 of the file at 11:36:05.9. If you work that fast (!), the new version will have the same modification time -- kept with 1 second resolution in Unix --, and -will not be refreshed.
For timing measurements and performance tuning, you can set the +will not be refreshed.
+For timing measurements and performance tuning, you can set the parameter
RefreshCachein sectiontemplatetoneveroralways. The former suppresses checking mtime and may improve performance on a production server, where the content pages don't change. The -latter is only inteded for testing.VII. Data Model Discussion
This packages doesn't need a data model.
It comes with its own database interfaces, one for using ns_ora, +latter is only inteded for testing.
+VII. Data Model Discussion
+This packages doesn't need a data model.
+It comes with its own database interfaces, one for using ns_ora, the Oracle driver from ArsDigita, and one for ns_db, the builtin database interface of the AOL server. If you are programming under the ACS, you should use neither of these, but rather the
db_*interface, in particular -db_multirow.VIII. User Interface
This packages doesn't have a user interface. It is the +
+db_multirow.VIII. User Interface
+This packages doesn't have a user interface. It is the substrate of all user interfaces, be it user or admin -pages.
IX. Configuration/Parameters
+pages. +IX. Configuration/Parameters
+ There are two parameters.[ns/server/yourservername/acs/template] @@ -251,13 +286,18 @@ ; anything other than "never" or "always" means normal operation RefreshCache=as necessary -X. Future Improvements/Areas of Likely Change
Passing datasources by reference is new. The acs-templating + +
X. Future Improvements/Areas of Likely Change
+Passing datasources by reference is new. The acs-templating syntax
&formal="actual"is different from the independent ATS, which usedformal="\@actual.*\@". The -latter is phased out.We intend to add a
+<which>, +latter is phased out.We intend to add a
<which>,<switch>, or<case>tag, to complement sequential nested -<if>/<else>constructs.Authors
-
+
<if>/<else>constructs. +Authors
+XII. Revision History
+ +
+XII. Revision History
+Document Revision # Action Taken, Notes When? By Whom? @@ -277,8 +319,10 @@ 0.2 Adapted to acs-templating as distributed with ACS/Tcl 4.01 22 Nov 2000 Christian Brechbühler
Christian -Brechbuehler +
+{/doc/acs-templating {Templating}} {Template Designer Guide} Template Designer Guide - - - Designer Guide
Templating System : Designer Guide -Overview
Templates are the primary means for separating the work of +
Designer Guide
+Templating System + : Designer Guide +Overview
+Templates are the primary means for separating the work of developers and designers. A template is written by a designer and consists largely of static HTML (or other markup). The template author uses a small set of special markup tags to reference dynamic data prepared by the developer.The tags allow authors to accomplish -four basic tasks that are not possible with standard HTML:
-
+four basic tasks that are not possible with standard HTML:
+
A reasonably skilled template author should be able to implement +
A reasonably skilled template author should be able to implement a template without any assistance from the developer, other than -assuring that the proper dynamic data is accessible.
Concepts
This section introduces the basic concepts underlying the use of -template tags in ACS 4.0.
Variable Substitution
Much like the mail merge feature of a word processor, template +assuring that the proper dynamic data is accessible.
+Concepts
+This section introduces the basic concepts underlying the use of +template tags in ACS 4.0.
+Variable Substitution
+Much like the mail merge feature of a word processor, template authors must use special tags to position each piece of dynamic data within the layout. Each template is associated with a data -dictionary that lists all available data sources.
Use of Components
To speed development and ensure consistency of design, template +dictionary that lists all available data sources.
+ +Use of Components
+To speed development and ensure consistency of design, template authors are encouraged to assemble pages from distinct component templates that may be recycled in different contexts. One typical practice is to build a "master" template for an entire section of a site, with a common header, footer and sidebar layout. For each page request, the "content" template is incorporated dynamically into a specified area of the master template, usually a table -cell.
(graphic)
Another common practice is to build small reusable templates +cell.
+(graphic)
+Another common practice is to build small reusable templates that may be included in other templates as logical components. This may be useful for common "widgets" such as search boxes or lists of related links, as well as for building configurable portal pages where users may assemble different types of content to their -liking.
(graphic)
See include and +liking.
+(graphic)
+See include and master. See also Building reusable layout components and -Using master templates.
Property Declarations
Template authors need a simple mechanism for declaring +Using master templates.
+Property Declarations
+Template authors need a simple mechanism for declaring properties within the templates. The most common use of such properties is for configuring elements of an enclosing master template, such as the title, navigation links, and whether to include a search box. The data dictionary specifies available -properties as well as the set of valid values when appropriate.
(graphic)
See property.
Conditional Insertion
Designers often need to tailor the layout depending on the +properties as well as the set of valid values when appropriate.
+(graphic)
+See property.
+Conditional Insertion
+Designers often need to tailor the layout depending on the specific data being presented. For example, when presenting a list of library books that a user has checked out, the designer might -want to highlight the overdue ones in red.
See if..else.
Iteration
Dynamic pages often present lists of values or records, each of +want to highlight the overdue ones in red.
+See if..else.
+Iteration
+Dynamic pages often present lists of values or records, each of which typically represents the results of a database query. Template authors must have a way to iterate over each value or record in such a list and format it appropriately. In the simplest scenario, the exact HTML is repeated with each iteration. However, template authors often need to vary the design depending on the -context. For example:
-
+context. For example:
+
To accomodate these type of scenarios, the template parser sets +
To accomodate these type of scenarios, the template parser sets some additional variables that the designer can reference to vary -the layout from item to item.
Notes
-
+the layout from item to item.
+
+
+
Notes
+
+Christian +Brechbuehler + +Last modified: Mon Oct 2 14:12:08 EDT 2000 \ No newline at end of file Index: openacs-4/packages/acs-templating/www/doc/developer-guide.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/developer-guide.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-templating/www/doc/developer-guide.adp 20 Aug 2015 17:19:52 -0000 1.2.2.1 +++ openacs-4/packages/acs-templating/www/doc/developer-guide.adp 25 Aug 2015 18:02:09 -0000 1.2.2.2 @@ -2,20 +2,25 @@{/doc/acs-templating {Templating}} {Template System Guide} Template System Guide - - - Programmer / Developer Guide
Templating System : Developer Guide +Programmer / Developer Guide
+Templating System + : Developer GuideMini How To
-Start a Tcl page as usual withad_page_contract. Be -sure to pass a-propertiesblock; this signals the use + +Start a Tcl page as usual withad_page_contract+. Be +sure to pass a-properties+ block; this signals the use of templating. The tcl page should fill the data sources you promised in the contract, and not write to the connection. At the -end of your tcl page, callad_return_template. The +end of your tcl page, callad_return_template+. The template system will look for an adp page with the file name stub you indicate (defaulting to the same stub as the tcl page), process that, and deliver it to the client. The adp page can use the datasources defined in the tcl page. -Guide
-
+
Guide
+API
+API
+ After the script for a page is executed, acs-templating processes the template, interpolating any data sources and executing the special tags. The resulting HTML page is written to the connection (i.e., returned to the user).
-Normally, does nothing at all. With thead_return_template-stringoption + +Normally, does nothing at all. With the-string+ option you get the resulting HTML page returned as a string.The optional
templateargument is a path to a page (tcl/adp file pair). Note that you don't supply the ".tcl" or @@ -68,18 +77,24 @@template::set_file, to change the name of the page being served currently. If it starts with a "/", it is taken to be a path relative to the server root; otherwise it is a filename -relative to the directory of the tcl script.
+relative to the directory of the tcl script. +ad_page_contract
+ Normally, complaints about incorrect parameters are written directly to the connection, and the script is aborted. With the -optionad_page_contract-return_errorsyou can name a variable into +option-return_errors+ you can name a variable into which to put any error messages as a list, and -ad_page_contractwill return in any case. You can then +ad_page_contract+ will return in any case. You can then present the errors to the user in a templated page, consistent with the look and feel of the rest of your service. If there's no -complaint,ad_page_contractwon't touch the variable; +complaint,ad_page_contract+ won't touch the variable; typically it will stay undefined. -
Christian -Brechbühler +
+Christian +Brechbühler + Last modified: $Id: developer-guide.html,v 1.4 2015/06/16 08:53:38 gustafn Exp $ - Index: openacs-4/packages/acs-templating/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/index.adp,v diff -u -N -r1.2.2.4 -r1.2.2.5 --- openacs-4/packages/acs-templating/www/doc/index.adp 21 Aug 2015 10:49:21 -0000 1.2.2.4 +++ openacs-4/packages/acs-templating/www/doc/index.adp 25 Aug 2015 18:02:10 -0000 1.2.2.5 @@ -2,11 +2,11 @@{/doc/acs-templating {Templating}} {Templates} Templates - - Templating System
+ Templating System -Document overview
+
+Document overview
+Requirements What the template system should do for you. @@ -29,15 +29,19 @@ API for programming the Tcl part of a page -API, TclDoc Object and API Reference +API, TclDocObject and API Reference Migration Bringing legacy tcl pages to use the template system. Demonstration Samples of the various mechanisms, with both Tcl and ADP parts. Release Notes
Please file bugs in the Bug Tracker.
Christian -Brechbühler +Release Notes
+Please file bugs in the Bug Tracker.
+
+Christian +Brechbühler + Last modified: $Id: index.html,v 1.6.2.2 2015/08/21 10:28:47 gustafn Exp $ - Index: openacs-4/packages/acs-templating/www/doc/install.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/install.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/install.adp 27 Oct 2014 16:40:13 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/install.adp 25 Aug 2015 18:02:10 -0000 1.2.2.1 @@ -2,66 +2,88 @@{/doc/acs-templating {Templating}} {Templating System: Installation} Templating System: Installation - - - Installation
The templating system may be used alone or in conjunction with +
Installation
+The templating system may be used alone or in conjunction with version 4.0 or greater of the ArsDigita Community System (ACS). The -following instructions apply to a standalone installation only.
Requirements
The templating system requires version 3.1 or greater of +following instructions apply to a standalone installation only.
+Requirements
+The templating system requires version 3.1 or greater of AOLserver for Unix or Windows. Until version 3.1 is officially released, you must use the ArsDigita distribution of AOLserver 3.0, which includes some required patches to the ADP -parser. These patches have been integrated into AOLserver 3.1.
To use the database interface for merging dynamic data with your +parser. These patches have been integrated into AOLserver 3.1.
+To use the database interface for merging dynamic data with your templates, you will also need to have installed any -AOLserver-compatible RDBMS.
Obtaining the distribution
To install the templating system, download and unpack the tar -file under your page root:
+AOLserver-compatible RDBMS. +
+Obtaining the distribution
+To install the templating system, download and unpack the tar +file under your page root:
+$ wget http://bob.sf.arsdigita.com:8089/ats/ats.tar.gz $ cd /web/myserver/www $ gunzip -c ats.tar.gz | tar xvf - -
The distribution consists of four subdirectories:
-
+
The distribution consists of four subdirectories:
+You can also untar (or check out) the distribution somewhere + +
You can also untar (or check out) the distribution somewhere else and symlink it under your page root. (If you do not wish to install the distribution under your page root, see the -configuration options below).
Installing the Tcl module
The templating system code is a Tcl-only module for AOLserver. +configuration options below).
+Installing the Tcl module
+The templating system code is a Tcl-only module for AOLserver. For AOLserver to load the module source code, you must move, copy or symlink the tcl directory in the templating system distribution to the private Tcl library of your AOLserver installation (as indicated by the Library parameter in the ns/server/myserver/tcl section of the AOLserver -configuration file):
+configuration file): +
+$ cd /web/myserver/tcl $ ln -s <path_to_distribution>/ats/tcl/ ats -
Configuring AOLserver
The last step is to modify your AOLserver configuration file. +
Configuring AOLserver
+The last step is to modify your AOLserver configuration file. You will need to register the templating system as a Tcl-only -module:
+module: +
+[ns/server/myserver/modules] nssock=nssock.so nslog=nslog.so ats=Tcl -
or if you are using the new configuration file format:
+
+or if you are using the new configuration file format:
+ns_section "ns/server/${server}/modules" ns_param nssock nssock.so ns_param nslog nslog.so ns_param ats Tcl -Note that you should replace ats with whatever you +
Note that you should replace ats with whatever you named the directory or symlink for the templating code within your -private Tcl library.
You will also need to ensure that the "fancy" ADP parser is the -default:
+private Tcl library. +
+You will also need to ensure that the "fancy" ADP parser is the +default:
+[ns/server/yourserver/adp] Map=/*.adp DefaultParser=fancy [ns/server/yourserver/adp/parsers] fancy=.adp -
Optional Configuration
The templating system recognizes two optional parameters in the +
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 relational database from the templating system. Two interfaces are @@ -82,8 +104,12 @@ directory, containing sitewide styles for forms, system messages, etc. Defaults to $::acs::pageroot/ats/resources. Testing the System
To test the system, run the script demo/demo.sql to -create and populate a simple table in your database.
Save the configuration file and restart the server. Use the +
Testing the System
+To test the system, run the script demo/demo.sql to +create and populate a simple table in your database.
+Save the configuration file and restart the server. Use the samples included in the distribution to test whether the system is -working properly.
templating\@arsdigita.com - +working properly. +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/introduction.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/introduction.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/introduction.adp 27 Oct 2014 16:40:13 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/introduction.adp 25 Aug 2015 18:02:10 -0000 1.2.2.1 @@ -2,11 +2,11 @@{/doc/acs-templating {Templating}} {Templating System: Goals} Templating System: Goals - - - Goals
The overall goal of the templating system is to provide the +
Goals
+The overall goal of the templating system is to provide the publishing team with a set of tools for simplifying the development -and maintenance of the user interface. In particular:
-
+and maintenance of the user interface. In particular:
+
templating\@arsdigita.com - +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/migration.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/migration.adp,v diff -u -N -r1.3.2.6 -r1.3.2.7 --- openacs-4/packages/acs-templating/www/doc/migration.adp 21 Aug 2015 10:49:22 -0000 1.3.2.6 +++ openacs-4/packages/acs-templating/www/doc/migration.adp 25 Aug 2015 18:02:10 -0000 1.3.2.7 @@ -2,31 +2,40 @@{/doc/acs-templating {Templating}} {Templating an Existing Tcl Page} Templating an Existing Tcl Page - - - Templating an Existing Tcl Page
Templating System : Migration +Templating an Existing Tcl Page
+Templating System + : MigrationIn 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. The +special tags and the\@variable\@+ construct. The code goes into a Tcl script. In other words, a templated page consists of two files, a Tcl part that puts its results in data sources, and an ADP page (the template), into which these data sources will be interpolated to yield a complete HTML page. -General
As usual, the Tcl page should start with a call to +
General
+As usual, the Tcl page should start with a call to
ad_page_contract. In its-propertiesblock you promise the data sources that your script will provide; they were earlier called page properties, hence the name of the option. Then your script performs all the computations and queries needed to define these data sources. There are special -mechanisms for handling multirow data sources; see below.At the end of the Tcl script, you should call +mechanisms for handling multirow data sources; see below.
+At the end of the Tcl script, you should call
ad_return_template. The template runs after the tcl -script, and can use these data sources.Make sure that the fancy adp parser is enabled in your AOL ini -file.
+script, and can use these data sources. +
Make sure that the fancy adp parser is enabled in your AOL ini +file.
+[ns/server/myserver/adp] DefaultParser=fancy -A few more hints
-
+
+
A few more hints
+Forms
+ +Forms
+ There is nothing special about building forms; just use the -<form>tag as always. All HTML tags can be used +<form>+ tag as always. All HTML tags can be used in the ADP file (template). -A simple page
First I take a page from the news package as an example. For +
A simple page
+First I take a page from the news package as an example. For simplicity, I pick
item-view, which does not use a<form>. I reformatted it a bit to make three -panes fit next to each other and to line up corresponding code.+panes fit next to each other and to line up corresponding code. +
+old tcl code new @@ -186,12 +200,17 @@ -Multi-Row Data Sources
+Multi-Row Data Sources
+ Technically, the result of a query that may return multiple rows is stored in several arrays. This datasource is filled by a call to -db_multirow, and the repeating part of the HTML output -is produced by the<multiple>tag. The following -example shows the part of theindexpage of the News +db_multirow+, and the repeating part of the HTML output +is produced by the<multiple>+ tag. The following +example shows the part of theindex+ page of the News module that uses the mechanism, not a whole page.
+ Notes:@@ -316,6 +335,7 @@ If you have a more complicated db_foreach, where logic is + +
If you have a more complicated db_foreach, where logic is performed inside the body, then it might be helpful to build your own multirow variable. In the excert below, taken from /pvt/alerts.tcl and /pvt/alerts.adp, the foreach logic made it hard to use the db_multirow because it needed a combination of the output from sql and also the output of tcl procedures using that -value.
+value. +
+old tcl code new @@ -540,11 +562,13 @@ -
+
+ Christian Brechbühler, Hiro Iwashima + Last modified: $Id: migration.html,v 1.3 2014/10/27 16:40:14 victorg Exp $ - Index: openacs-4/packages/acs-templating/www/doc/no-quote-upgrade.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/no-quote-upgrade.adp,v diff -u -N -r1.3.2.1 -r1.3.2.2 --- openacs-4/packages/acs-templating/www/doc/no-quote-upgrade.adp 20 Aug 2015 17:19:53 -0000 1.3.2.1 +++ openacs-4/packages/acs-templating/www/doc/no-quote-upgrade.adp 25 Aug 2015 18:02:10 -0000 1.3.2.2 @@ -2,34 +2,43 @@{/doc/acs-templating {Templating}} {Upgrading existing ADPs to noquote templating} Upgrading existing ADPs to noquote templating + Upgrading existing ADPs to noquote templating
+Introduction.
- -Upgrading existing ADPs to noquote templating
Introduction.
The variable substitution in the templating has been changed to become more friendly towards quoting. The rationale for the change -and the definition of terms like quoting are present in -the quoting article. As it discusses +and the definition of terms like quoting + are present in +the quoting article +. As it discusses these concepts in some depths, we see no reason to repeat them here. Instead, we will assume that you have read the previous article and focus on the topic of this one: the changes you need to apply to make your module conformant to the new quoting rules.This text is written as a result of our efforts to make the ACS installation for the German Bank project work, therefore it is based on field experience rather than academic discussion. We hope -you will find it useful.
Recap of the Theory.
+you will find it useful. +Recap of the Theory.
+ The change to the templating system can be expressed in one sentence:All variables are now quoted by default, except those explicitly protected by ;noquote 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 that +;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 means that +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.This is not hard because most variables will not be affected by this change. Most variables either need to be quoted (those @@ -39,53 +48,65 @@ contain HTML which is expected to be included as part of the page, and those that are already quoted by Tcl code. Such variables should be protected from quoting by the ;noquote -modifier.
The Most Common Cases.
-The most common cases where you need to add ;noquote to +modifier. +The Most Common Cases.
+ +The most common cases where you need to add ;noquote + to the variable name are easy to recognize and identify.Hidden form variables.
Also known as "hidden input fields", hidden form variables are form fields with pre-defined values which are not shown to the user. These days they are used for transferring internal state across several form pages. In HTML, hidden form variables look like -this:
++this: +
+ 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 to a variable:<form> <input name=var1 value="value1"> <input name=var2 value="value2"> ... real form stuff ... </form>
-The ADP will simply refer to the form_vars variable: + +The ADP will simply refer to the form_vars + variable:set form_vars [export_vars -form {var1 var2}]
+ 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> \@form_vars\@ <!-- WRONG! Needs noquote --> ... real form stuff ... </form><form> \@form_vars;noquote\@ ... real form stuff ... </form> -+
Snippets of HTML produced by Tcl code, aka widgets .
@@ -96,26 +117,33 @@ widget programmatically and include it into the template as a variable. A typical widget is a date entry widget which provides the user the input and selection boxes for year, month, and day, -all of which default to the current date.Another example of widgets is the context bar often found -on top of ACS pgages.
Obviously, all widgets should be treated as HTML and therefore +all of which default to the current date.
+Another example of widgets is the context bar often found +on top of ACS pgages.
+Obviously, all widgets should be treated as HTML and therefore adorned with the ;noquote qualifier. This also assumes that the routines that build the widget are correctly written and that they will quote the components used to -build the widget.
+build the widget.
+Pieces of text that are already quoted.
This quoting is usually part of a more general preparation for HTML rendering of the text. For instance, a bboard posting can be either HTML or text. If it is HTML, we transmit it as is; if not, we perform quoting, word-wrapping, etc. In both cases it is obvious that quoting performed by the templating system would be redundant, -so we must be careful to add ;noquote to the ADP.The property and include Gotchas.
+so we must be careful to add ;noquote to the ADP. +The property and include Gotchas.
+ Transfer of parameters between included ADPs often requires manual -addition of ;noquote. Let's review why. +addition of ;noquote +. Let's review why.The property tag is used to pass a piece of information to the master template. This is used by the ADP whose writer consciously chose to let the master template handle a variable given by the Tcl code. Typically page titles, headings, and context -bars are handled this way. For example:
+bars are handled this way. For example: +
master:
+ The obvious intention of the master is to allow its slave templates to provide a "title" and a "heading" of the page in a standardized fashion. The obvious intention of our slave template is to allow its corresponding Tcl code to set a single variable, -title, which will be used for both title and heading. +title +, which will be used for both title and heading. What's wrong with this code?<head> <title>\@title\@</title> @@ -133,19 +161,22 @@The problem is that title gets quoted twice, once by the slave template, and once by the master template. This is the result of how the templating system works: every occurrence of \@variable\@ is converted to [ad_quotehtml $variable], even when it is used only to set a property and you would expect the quoting to be -suppressed.
Implementation note: Ideally, the +suppressed. +
+Implementation note: Ideally, the templating system should avoid this pitfall by quoting the variable (or not) only once, at the point where the value is passed from the Tcl code to the templating system. However, no such point in time @@ -155,13 +186,15 @@ to the master so that all the property variables are shoved into an environment; by the time the master template is executed, all information on which variable came from where and whether it might -have already been quoted is lost.
This occurrence is often referred to as over-quoting. +have already been quoted is lost.
This occurrence is often referred to as over-quoting. Over-quoting is sometimes hard to detect because things seem to work fine in most cases. To notice the problem in the example above (and in any other over-quoting example), the title needs to contain one of the characters <, > or &. If it does, they will appear quoted to the user -instead of appearing as-is.
Over-quoting is resolved by adding ;noquote to one of +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 reason is that, first, it makes sense to do so because conceptually @@ -171,17 +204,21 @@ it is much cleaner and more maintainable if this transfer is defined to be non-lossy. This becomes important in practice when there is a hierarchy of master templates -- e.g. one for -the package and one for the whole site.
To reiterate, a bug-free version of the slave template looks -like this:
+the package and one for the whole site. +
To reiterate, a bug-free version of the slave template looks +like this:
+slave sans over-quoting:
<master> <property name="doc(title)">\@title;literal\@</property> <property name="heading">\@title;literal\@</property> ...-The exact same problems when the include statement -passes some text. Here is an example:
+
+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 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\@> @@ -194,21 +231,27 @@What happens is that reason that prefills the textarea is over-quoted. The reasons are the same as in the last example: it gets quoted once by the includer, and the second time by the included page. The fix is also similar: when you transfer non-constant text to an included page, make sure to add -;literal.
+;literal. +
+Including template, sans over-quoting:
<include src="user-kick-form" id=\@kicked_id;literal\@ reason=\@default_reason;literal\@>-Upgrade Overview.
+Upgrade Overview.
+ Upgrading a module to handle the new quoting rules consists of applying the process mentioned above to every ADP in the module. Using the knowledge gained above, we can specify exactly what needs @@ -228,9 +271,11 @@ quoting.Testing.
+ Fortunately, most of the problems with automatic quoting are very easy to diagnose. The most important point for testing is that it covers as many cases as possible: ideally testing should cover all @@ -268,7 +313,9 @@ such as a context bar, from strings that come from the database or from the user. -
Hrvoje -NiksicLast modified: Thu Aug 20 18:38:05 CEST 2015 - - + +
+Hrvoje +Niksic +Last modified: Thu Aug 20 18:38:05 CEST 2015 + \ No newline at end of file Index: openacs-4/packages/acs-templating/www/doc/noquote.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/noquote.adp,v diff -u -N -r1.3.2.1 -r1.3.2.2 --- openacs-4/packages/acs-templating/www/doc/noquote.adp 20 Aug 2015 17:19:53 -0000 1.3.2.1 +++ openacs-4/packages/acs-templating/www/doc/noquote.adp 25 Aug 2015 18:02:10 -0000 1.3.2.2 @@ -4,11 +4,11 @@HTMLQuoting as Part of the Templating System - Requirements - - - ++ +-HTMLQuoting as @@ -182,14 +182,10 @@ after the change, is also available .
View -comments on this page at openacs.org - ++ \ No newline at end of file Index: openacs-4/packages/acs-templating/www/doc/requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/requirements.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-templating/www/doc/requirements.adp 20 Aug 2015 17:19:53 -0000 1.2.2.1 +++ openacs-4/packages/acs-templating/www/doc/requirements.adp 25 Aug 2015 18:02:10 -0000 1.2.2.2 @@ -2,18 +2,26 @@ {/doc/acs-templating {Templating}} {ACS Templating Requirements} ACS Templating Requirements - - ACS Templating Requirements
-by Karl Goldstein, + +by Karl Goldstein +, Christian -Brechbühler, Peter -Su, and Yonatan FeldmanI. Introduction
+Brechbühler +, Peter +Su +, and Yonatan Feldman + +I. Introduction
+ The following is a requirements document for the ACS Templating System version 0.5. It has also been called Karl's Templates, the Dynamic Publishing System (DPS), and Stencil. The official package -name for the system is nowacs-templating. -II. Vision Statement
+name for the system is nowacs-templating+. + +II. Vision Statement
+ On websites of sufficient size, a consistent look and feel (the UI, or user interface) for users is important, while for site publishers and administrators, de-coupling the UI from programming @@ -27,7 +35,9 @@ fills the blanks in the template. In addition, the templating system provides a way to use a single layout specification for the majority - if not all - of a website's pages, so the overall layout -of a site can be more easily administered.III. System Overview
+of a site can be more easily administered. +III. System Overview
+ The templating system provides:IV. Use-cases and User-scenarios
The template system is designed to be used by two classes of + + +
IV. Use-cases and User-scenarios
+The template system is designed to be used by two classes of users: programmers and designers. In bulding a web site, programmers are generally responsible for defining and implementing the application logic of the site, while designers are more @@ -47,10 +60,13 @@ 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 +something that the user sees as a single page.
+Thus, pages are naturally split into two parts. The logic part executes application logic and generates data, and the presentation part that specifies the layout of the page and -so on.
What is needed is:
-
+so on.
+
What is needed is:
+Jane Programmer writes a page contract and a draft template, +
Jane Programmer writes a page contract and a draft template, that uses the promised page properties. Joe Designer takes that template and makes it look nice, using his design skills and HTML literacy. Meanwhile Jane Programmer writes code to generate the page properties, typically by querying the database. When both are done, the page is ready for Jim User, who requests it using his web -browser.
+browser.
+Alternate scenario: Judy Designer is familiar with the template system. She starts directly from a defined page contract, -so Jane Programmer doesn't need to write the draft template.
V. Related Links
VI.A Functional Requirements
-
+so Jane Programmer doesn't need to write the draft template.
+
V. Related Links
+VI.A Functional Requirements
+VI.B Non-functional Requirements
-
+
VI.B Non-functional Requirements
+VII. Revision History
+ +
+VII. Revision History
+Document Revision # Action Taken, Notes When? By Whom? @@ -195,7 +223,9 @@ 0.3 Edited, reviewed, pending freeze 8/28/2000 Kai Wu
yon\@arsdigita.com +
+{/doc/acs-templating {Templating}} {Template Timing Results} Template Timing Results - - Results
-The measurements were taken ondev0103-001on 5 + +The measurements were taken ondev0103-001+ on 5 October 2000, probably with acs-4-0-beta-R20001001. Here are the graphs for the 14 stages, titled by the log message of their beginning. -Invoking preauth filter rp_filter
No difference; all take about 2.6 ms. The same is the case for +
Invoking preauth filter rp_filter
+
+No difference; all take about 2.6 ms. The same is the case for the few following stages: Short times and apparently independent of -the kind of page.
Looking for node to match -/acs-templating/admin/test/chain-frac-0.
Found /acs-templating/.
Performing developer support logging
Checking for changed libraries
Handling authentication
For some reason, this seems to take much longer on the Tcl-only +the kind of page.
+Looking for node to match +/acs-templating/admin/test/chain-frac-0.
+
+Found /acs-templating/.
+
+Performing developer support logging
+
+Checking for changed libraries
+
+Handling authentication
+
+For some reason, this seems to take much longer on the Tcl-only page. Maybe because it's the first in a triple of pages that e-Tester requests? There may be a little longer time gap between -chain-frac-2 and the next request of chain-frac-0
Handling authorization
An unexplained but clear distinction here: 0 is faster than 2, -and 1 is slowest.
Done invoking preauth filter rp_filter (returning -filter_ok)
Invoking registered procedure rp_handler
Searching for -/webroot/web/brech/acs/packages/acs-templating/www/admin/test/chain-frac-0.*
Serving +chain-frac-2 and the next request of chain-frac-0 +
Handling authorization
+
+An unexplained but clear distinction here: 0 is faster than 2, +and 1 is slowest.
+Done invoking preauth filter rp_filter (returning +filter_ok)
+
+Invoking registered procedure rp_handler
+
+Searching for +/webroot/web/brech/acs/packages/acs-templating/www/admin/test/chain-frac-0.*
+
+Serving /webroot/web/brech/acs/packages/acs-templating/www/admin/test/chain-frac-0.tcl -with rp_handle_tcl_request
Here the actual work supposedly happens. The Tcl-only page is +with rp_handle_tcl_request +
+Here the actual work supposedly happens. The Tcl-only page is clearly fastest. Always reparsing pages expectedly affects the templated page, and -2, which compiles two ADP pages, is affected more than -1. The benefit of -2, wrapping -1 in another include, isn't apparent; on the contrary, -1 is in all cases a bit faster than -2. The benefit of cacheing seems more than offset by the -extra complexity of nesting several templates.
Invoking trace filter ad_issue_deferred_dml
For some reason, the Tcl-only page takes significantly -longer.
Done invoking trace filter ad_issue_deferred_dml (returning -filter_ok)
Invoking trace filter ds_trace_filter
That last phase is ended by Done invoking trace filter +extra complexity of nesting several templates.
+Invoking trace filter ad_issue_deferred_dml
+
+For some reason, the Tcl-only page takes significantly +longer.
+Done invoking trace filter ad_issue_deferred_dml (returning +filter_ok)
+
+Invoking trace filter ds_trace_filter
+
+That last phase is ended by Done invoking trace filter ds_trace_filter (returning filter_ok) -
Total time
Overall, the templated pages are delivered faster. +
+Total time
+
+Overall, the templated pages are delivered faster. Forcing the template system to always reread all files and to recompile the ADP part slows them down, as expected, but overall -they are still faster than the Tcl-only page.
Christian -Brechbuehler -Last modified: Tue Oct 17 20:04:29 EDT 2000 - +they are still faster than the Tcl-only page. +
+Christian +Brechbuehler + +Last modified: Tue Oct 17 20:04:29 EDT 2000 \ No newline at end of file Index: openacs-4/packages/acs-templating/www/doc/timing-2.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/timing-2.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/timing-2.adp 27 Oct 2014 16:40:14 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/timing-2.adp 25 Aug 2015 18:02:10 -0000 1.2.2.1 @@ -2,22 +2,43 @@{/doc/acs-templating {Templating}} {Template Timing Results} Template Timing Results - - Results
-The measurements were taken onreusia.bostonon 13 + +The measurements were taken onreusia.boston+ on 13 October 2000, with approximately acs-4-0-beta-2-R20001009.Here are the graphs for the 15 stages, and the log message of their beginning is written in the lower right of the graphs. In comparison with the first measurement, the steeper slopes indicate much less variation in the measurements, which reflects the more reproducible conditions (essentially no other activity) on reusia.boston in comparison with -dev0103-001.
Individual Stages
Total Time (Sum of all Stages)
Overall, the templated pages are delivered markedly +dev0103-001.
+Individual Stages
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Total Time (Sum of all Stages)
+
+Overall, the templated pages are delivered markedly slower, by about 65ms. Forcing the template system to always reread all files and to recompile the ADP part slows them down, as expected, but overall they are still faster than the Tcl-only -page.
Christian -Brechbuehler -Last modified: Wed Oct 18 16:45:17 EDT 2000 - +page. +
+Christian +Brechbuehler + +Last modified: Wed Oct 18 16:45:17 EDT 2000 \ No newline at end of file Index: openacs-4/packages/acs-templating/www/doc/timing-3.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/timing-3.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/timing-3.adp 27 Oct 2014 16:40:15 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/timing-3.adp 25 Aug 2015 18:02:11 -0000 1.2.2.1 @@ -2,24 +2,41 @@{/doc/acs-templating {Templating}} {Template Timing Results} Template Timing Results - - - Results
The measurements were taken on
reusia.bostonon 17 +Results
+The measurements were taken on
reusia.bostonon 17 October 2000, with tarball acs-3-4-6-R20001008. Templating under 3.4 is quite different; instead of a .tcl script, datasources are -defined in a .data file that has a different XML syntax.We have graphs for 9 stages only. While Tcl pages generate four +defined in a .data file that has a different XML syntax.
+We have graphs for 9 stages only. While Tcl pages generate four more entries, these lack from templated pages, and hence I suppressed them. The log message that marks the beginning of each phase is written in the lower right of the graphs. Each curve curve plots 288 page requests. As I didn't back port of the configurable cache refreshing stragegy ('never' or 'always'), I show all graphs -in the 'normal' colors. The label is 'do', though.
Individual Stages
Total Time (Sum of all Stages)
To show off the graphing method, compare the graph above with +in the 'normal' colors. The label is 'do', though.
+Individual Stages
+
+
+
+
+
+
+
+
+
+Total Time (Sum of all Stages)
+
+To show off the graphing method, compare the graph above with the one below, which only uses the first 32 measurements. The -curves are less smooth, but the message is the same.
In ACS 3.4.6, Tcl-only pages are sereved faster than in +curves are less smooth, but the message is the same.
+
+In ACS 3.4.6, Tcl-only pages are sereved faster than in 4.0 beta-2. The templated pages are delivered much slower. The first time the template system reads a templated page, it takes about 3 seconds! The result is cached, mitigating the problem a -lot.
Christian -Brechbuehler -Last modified: Tue Oct 17 20:26:14 EDT 2000 - +lot. +
+Christian +Brechbuehler + +Last modified: Tue Oct 17 20:26:14 EDT 2000 \ No newline at end of file Index: openacs-4/packages/acs-templating/www/doc/timing.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/timing.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/timing.adp 27 Oct 2014 16:40:15 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/timing.adp 25 Aug 2015 18:02:11 -0000 1.2.2.1 @@ -2,22 +2,27 @@{/doc/acs-templating {Templating}} {Timing a Templated Page} Timing a Templated Page - - Timing a Templated Page
+ by Christian -BrechbühlerI. Introduction
-One of the requirements for the +Brechbühler +I. Introduction
+ +One of the requirements + for the template system asks for efficiency:
+ This page documents the attempt to verify this requirement. -II. Methods
I wrote a sample page for this test. It expands four real -numbers into continued fractions. I created three versions:
-
+
II. Methods
+I wrote a sample page for this test. It expands four real +numbers into continued fractions. I created three versions:
+The reason for creating
chain-frac-2.adpis that in +The reason for creating
chain-frac-2.adpis that in this way, the scriptchain-frac-1.tclis handled inside the templating system, and hence loaded once and cached. -There is hope that this might be faster.Normally, the templating system re-reads a file whenever the +There is hope that this might be faster.
+Normally, the templating system re-reads a file whenever the version on disk is out of date. ADP pages are compiled to TCL, and both ADP and Tcl pages are cached as Tcl procs. The parameter
RefreshCachein sectiontemplatecan be set toalwaysorneverto affect the cacheing strategy; the latter may be useful for a production site. All timing is carried out for the three settingsalways,normal, andnever; -the associated variable is calledcheck.I created a script in e-Tester that requests the three pages +the associated variable is called
+check.I created a script in e-Tester that requests the three pages from my development server on dev0103-001. One timing of requesting a page isn't very expressive. A lot of factors affect the page load time. To offset these and get better results, I repeatedly request the pages. For the timing, I have e-Tester iterate this script 200 times. To compesate for varying load on the machine, i ran the iteration twice for each setting of
RefreshCacheat -different times of the day.The timing information is taken from the error log file entries +different times of the day.
+The timing information is taken from the error log file entries that the request processor produces with parameter
LogDebugP=1. For finer granularity I changed rp_debug to divide the clock clicks (microsecond) difference by 1000.0 @@ -54,8 +63,10 @@ I note the length of the error log before and after one run of the script. Afterwards I cut out the error log sections indicated by these positions into filesnever,normal, -andalways.The following steps extract the relevant information and bring -it in a form suitable for gnuplot.
-
+and
always. +The following steps extract the relevant information and bring +it in a form suitable for gnuplot.
+{/doc/acs-templating {Templating}} {} - - - Data Source API
We need to resolve how onerow and multirow data sources are +
Data Source API
+We need to resolve how onerow and multirow data sources are represented internally, and plug in the proper API. I originally used ns_sets to represent rows in a data source (and continue to do so for the time being). jsalz instead uses arrays and lists to represent rows. Task: look at jsalz's data source code.
- Index: openacs-4/packages/acs-templating/www/doc/TclDocs/cm_widget.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/cm_widget.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/TclDocs/cm_widget.adp 27 Oct 2014 16:40:15 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/cm_widget.adp 25 Aug 2015 18:02:11 -0000 1.2.2.1 @@ -2,15 +2,21 @@{/doc/acs-templating {Templating}} {} + Namespace cm_widget
+Procedures associated with custom metadata widgets for +basic CR content types
+Method Summary
- -Namespace cm_widget
Procedures associated with custom metadata widgets for -basic CR content types
Method Summary
-Listing of public methods:The namespace cm_widget currently contains no public -methods.
Method Detail
-* indicates required
+Listing of public methods:
+The namespace cm_widget currently contains no public +methods.
+Method Detail
++* indicates required
+Private Methods:
-+ +
-cm_widget::validate_description
by Michael Pih@@ -24,6 +30,6 @@ +
* indicates required
- Index: openacs-4/packages/acs-templating/www/doc/TclDocs/cms_rel.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/cms_rel.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/TclDocs/cms_rel.adp 27 Oct 2014 16:40:15 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/cms_rel.adp 25 Aug 2015 18:02:11 -0000 1.2.2.1 @@ -2,14 +2,21 @@{/doc/acs-templating {Templating}} {} + Namespace cms_rel
+Procedures for managing relation items and child +items
+Method Summary
- -Namespace cms_rel
Procedures for managing relation items and child -items
Method Summary
-Listing of public methods:+Listing of public methods:
+cms_rel::sort_child_item_order
cms_rel::sort_related_item_order
-Method Detail
-* indicates required
Public Methods:+ +
Method Detail
++* indicates required
+Public Methods: +
+
-cms_rel::sort_child_item_order
by Michael Pih@@ -24,7 +31,8 @@ +
+
-cms_rel::sort_related_item_order
by Michael Pih@@ -39,6 +47,6 @@ +
* indicates required
- Index: openacs-4/packages/acs-templating/www/doc/TclDocs/content.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/content.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/TclDocs/content.adp 27 Oct 2014 16:40:15 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/content.adp 25 Aug 2015 18:02:11 -0000 1.2.2.1 @@ -2,14 +2,21 @@{/doc/acs-templating {Templating}} {} + Namespace content
+Procedures for generating and processing content +content creation and editing forms..
+Method Summary
- -Namespace content
Procedures for generating and processing content -content creation and editing forms..
Method Summary
-Listing of public methods:+Listing of public methods:
+content::add_attribute_element
content::add_attribute_elements
content::add_basic_revision
content::add_child_relation_element
content::add_content
content::add_content_element
content::add_revision
content::add_revision_form
content::copy_content
content::get_attribute_enum_values
content::get_latest_revision
content::get_object_id
content::new_item
content::new_item_form
content::validate_name
-Method Detail
-* indicates required
Public Methods:+ +
Method Detail
++* indicates required
+Public Methods: +
+
-content::add_attribute_element Add a form element (possibly a compound widget) to an ATS form object. for entering or editing an attribute @@ -39,7 +46,8 @@
+
+content::add_attribute_elements Add form elements to an ATS form object for all attributes of a content type.
-
@@ -65,7 +73,8 @@
- Returns:
- The list of attributes that were added.
+
+
-content::add_basic_revision Create a basic new revision using the content_revision PL/SQL API.
-
@@ -98,7 +107,8 @@
+
+
-content::add_child_relation_element Add a select box listing all valid child relation tags. The form must contain a parent_id element and a content_type @@ -122,7 +132,8 @@
+
+
-content::add_content Update the BLOB column of a revision with content submitted in a form
- @@ -133,7 +144,8 @@
+
+
-content::add_content_element Adds a content input element to an ATS form object.
- @@ -151,7 +163,8 @@
+
+
-content::add_revision Create a new revision for an existing item based on a valid form submission. Queries for attribute names and inserts a @@ -173,7 +186,8 @@
+
+
-content::add_revision_form Adds elements to an ATS form object for adding a revision to an existing item. If the item already exists, element @@ -208,7 +222,8 @@
+
+
-content::copy_content Update the BLOB column of one revision with the content of another revision
- @@ -227,7 +242,8 @@
+
+
-content::get_attribute_enum_values Returns a list of { pretty_name enum_value } for an attribute of datatype enumeration.
- @@ -239,7 +255,8 @@
+
+content::get_latest_revision Get the ID of the latest revision for the specified content item.
- @@ -250,10 +267,12 @@
+
+content::get_object_id Grab an object ID for creating a new ACS object.
+
+content::new_item Create a new item, including the initial revision, based on a valid form submission.
-
@@ -276,7 +295,8 @@
+
+
-content::new_item_form Adds elements to an ATS form object for creating an item and its initial revision. If the form does not already exist, @@ -311,7 +331,8 @@
+
+content::validate_name Make sure that name is unique for the folder
-
@@ -325,9 +346,11 @@
- Returns:
- 0 if there are items with the same name, 1 otherwise
+
Private Methods:
-+ +
content::add_revision_dml Perform the DML to insert a revision into the appropriate input view.
-
@@ -361,7 +384,8 @@
+
+
-content::attribute_insert_statement Prepare the insert statement into the attribute input view for a new revision (see the content repository documentation @@ -391,7 +415,8 @@
+
+
-content::get_attribute_params Query for parameters associated with a particular attribute
- @@ -410,7 +435,8 @@
+
+
-content::get_attributes Returns columns from the acs_attributes table for all attributes associated with a content type.
- @@ -429,7 +455,8 @@
+
+
-content::get_default_content_method Gets the content input method most appropriate for an content type, based on the MIME types that are registered for that @@ -442,7 +469,8 @@
+
+
-content::get_sql_value Return the sql statement for a column value in an insert or update statement, using a bind variable for the actual @@ -462,7 +490,8 @@
+
+content::get_type_attribute_params Query for attribute form metadata
- @@ -476,7 +505,8 @@ parameters, there is a single entry with is_html as null.
+
+
-content::get_type_info Return specified columns from the acs_object_types table.
- @@ -499,7 +529,8 @@
+
+
-content::get_widget_param_value Utility procedure to return the value of a widget parameter
- @@ -518,7 +549,8 @@
+
+content::prepare_content_file Looks for an element named { content} in a form and prepares a temporarily file in UTF-8 for uploading to the content @@ -538,7 +570,8 @@ value of the element is null.
+
+
-content::set_attribute_values Set the default values for attribute elements in ATS form object based on a previous revision
- @@ -566,7 +599,8 @@
+
+
-content::set_content_value Set the default value for the content text area in an ATS form object based on a previous revision
- @@ -584,7 +618,8 @@
+
+
-content::string_to_file Write a string in UTF-8 encoding to of temp file so it can be uploaded into a BLOB (which is blind to character @@ -596,7 +631,8 @@
+
+
-content::update_content_from_file Update the BLOB column of a revision with the contents of a file
- @@ -614,7 +650,8 @@
+
+
-content::upload_content Inserts content into the database from an uploaded file. Does automatic mime_type updating Parses text/html content @@ -644,6 +681,6 @@
+
* indicates required
- Index: openacs-4/packages/acs-templating/www/doc/TclDocs/content_add.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/content_add.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/TclDocs/content_add.adp 27 Oct 2014 16:40:15 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/content_add.adp 25 Aug 2015 18:02:11 -0000 1.2.2.1 @@ -2,13 +2,20 @@{/doc/acs-templating {Templating}} {} + Namespace content_add
+Procedures regarding content methods
+Method Summary
- -Namespace content_add
Procedures regarding content methods
Method Summary
-Listing of public methods:+Listing of public methods:
+content_add::content_method_html
-Method Detail
-* indicates required
Public Methods:+ +
Method Detail
++* indicates required
+Public Methods: +
+
-content_add::content_method_html
by Michael Pih@@ -31,6 +38,6 @@ +
* indicates required
- Index: openacs-4/packages/acs-templating/www/doc/TclDocs/content_method.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/content_method.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/TclDocs/content_method.adp 27 Oct 2014 16:40:16 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/content_method.adp 25 Aug 2015 18:02:11 -0000 1.2.2.1 @@ -2,13 +2,20 @@{/doc/acs-templating {Templating}} {} + Namespace content_method
+Procedures regarding content methods
+Method Summary
- -Namespace content_method
Procedures regarding content methods
Method Summary
-Listing of public methods:+Listing of public methods:
+content_method::flush_content_methods_cache
content_method::get_content_methods
-Method Detail
-* indicates required
Public Methods:+ +
Method Detail
++* indicates required
+Public Methods: +
+
-content_method::flush_content_methods_cache
by Michael Pih@@ -22,7 +29,8 @@ +
+content_method::get_content_methods
by Michael Pih@@ -45,9 +53,11 @@ +
Private Methods:
-+ +
+content_method::get_content_method_options
by Michael Pih@@ -66,7 +76,8 @@ +
+content_method::text_entry_filter_sql
by Michael Pih@@ -82,6 +93,6 @@ method +
* indicates required
- Index: openacs-4/packages/acs-templating/www/doc/TclDocs/doc.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/doc.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/TclDocs/doc.adp 27 Oct 2014 16:40:16 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/doc.adp 25 Aug 2015 18:02:12 -0000 1.2.2.1 @@ -2,14 +2,19 @@{/doc/acs-templating {Templating}} {} + Namespace doc
+Method Summary
- -Namespace doc
Method Summary
-Listing of public methods:The namespace doc currently contains no public -methods.
Method Detail
-* indicates required
+Listing of public methods:
+The namespace doc currently contains no public +methods.
+Method Detail
++* indicates required
+Private Methods:
-+ +
-
by simon@@ -23,7 +28,8 @@ +
++
+called by parse_comment_text
-
Parameters:
@@ -49,7 +56,8 @@
+
+called by parse_namespace
-
Parameters:
@@ -65,7 +73,8 @@
+
+takes the absolute path of the tcl library directory and parses through it
-
@@ -76,6 +85,6 @@
+
* indicates required
- Index: openacs-4/packages/acs-templating/www/doc/TclDocs/doc__util.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/doc__util.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/TclDocs/doc__util.adp 27 Oct 2014 16:40:16 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/doc__util.adp 25 Aug 2015 18:02:12 -0000 1.2.2.1 @@ -2,20 +2,26 @@{/doc/acs-templating {Templating}} {} + Namespace doc::util
+Method Summary
- -Namespace doc::util
Method Summary
-Listing of public methods:The namespace doc::util currently contains no public -methods.
Method Detail
-* indicates required
+Listing of public methods:
+The namespace doc::util currently contains no public +methods.
+Method Detail
++* indicates required
+Private Methods:
-+ +
+
+
-divides a string variable into a list of strings, all but the first element beginning with the indicated text {marker;} @@ -34,13 +40,15 @@
the string indicating text division - See Also:
- proc - doc::util::find_marker_indices
+- See Also:
- proc - doc::util::find_marker_indices
-
+
+escapes out all square brackets
+
+given a body of text and a text marker, returns a list of position indices for each occurrence of the text @@ -60,15 +68,17 @@
- Returns:
- list of indices of the position immediately preceding each occurrence of the text marker; if there are no occurrences of the text marker, returns a zero-element list
- See Also:
- namespace - doc
-- proc - doc::parse_file
doc::parse_namespace
doc::util::text_divider
+- proc - doc::parse_file
doc::parse_namespace
doc::util::text_divider
+
+puts a space after all closing curly brackets, does not add a space when brackets are already followed by a space
+
+
-used to sort the see list, which has structure {[name} name type type url url \]
- @@ -86,10 +96,12 @@
+
++
++
* indicates required
- Index: openacs-4/packages/acs-templating/www/doc/TclDocs/form.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/form.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/TclDocs/form.adp 27 Oct 2014 16:40:16 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/form.adp 25 Aug 2015 18:02:12 -0000 1.2.2.1 @@ -2,14 +2,21 @@{/doc/acs-templating {Templating}} {} + Namespace form
+Commands for managing dynamic templated +forms.
+Method Summary
- -Namespace form
Commands for managing dynamic templated -forms.
Method Summary
-Listing of public methods:+Listing of public methods:
+
-Method Detail
-* indicates required
Public Methods:+
+Determine whether a form exists by checking for its data structures.
-
@@ -44,7 +52,8 @@
not.
+
+Generates hidden input tags for all values in a form submission. Typically used to create a confirmation page following @@ -53,7 +62,8 @@ form.
+
+Initialize the data structures for a form.
- @@ -81,7 +91,8 @@
+
+
-Return a list which represents the result of getting combined values from multiple form elements
- @@ -104,7 +115,8 @@
+
+Return the number of elements in a form
-
Parameters:
@@ -114,7 +126,8 @@
+
+Return true if a submission in progress. The submission may or may not be valid.
-
@@ -127,7 +140,8 @@
- Returns:
- 1 if true or 0 if false
+
+Return true if preparing a form for an initial request (as opposed to repreparing a form that is returned to the user due @@ -142,7 +156,8 @@
- Returns:
- 1 if true or 0 if false
+
+Return true if submission in progress and submission was valid. Typically used to conditionally execute DML and redirect @@ -157,7 +172,8 @@
- Returns:
- 1 if true or 0 if false
+
+
-Set local variables for form variables (assume they are all single values). Typically used when processing the form @@ -177,7 +193,8 @@
+
+
-Set the name of the current section of the form. A form may be divided into any number of sections for layout purposes. @@ -197,9 +214,11 @@
+
Private Methods:
-+ +
Auto-generate the template for a form
- @@ -219,11 +238,13 @@
- Returns:
- A string containing a template for the body of the form.
+
+Helper procedure used to access the basic data structures of a form object. Called by several of the form commands.
+
+
-Iterates over all declared elements, checking for hidden widgets and rendering those that have not been rendered yet. @@ -236,7 +257,8 @@
+
+Render the HTML FORM tag along with a hidden element that identifies the form object.
-
@@ -256,7 +278,8 @@
- Returns:
- A string containing the rendered tags.
+
+Render the finished HTML output for a dynamic form.
-
@@ -277,6 +300,6 @@
- Returns:
- A string containing the HTML for the body of the form.
+
* indicates required
- Index: openacs-4/packages/acs-templating/www/doc/TclDocs/item.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/item.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/TclDocs/item.adp 27 Oct 2014 16:40:17 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/item.adp 25 Aug 2015 18:02:12 -0000 1.2.2.1 @@ -2,17 +2,26 @@{/doc/acs-templating {Templating}} {} - - - Namespace item
The item commands allow easy access to properties of +
+Namespace item
+The item commands allow easy access to properties of the content_item object. In the future, a unified API for caching -item properties will be developed here.
Also see:
-
+item properties will be developed here.
Also see:
+- namespace
- publish -
Method Summary
-Listing of public methods:+ +
Method Summary
+ +Listing of public methods:
+item::content_is_null
item::content_methods_by_type
item::get_best_revision
item::get_content_type
item::get_extended_url
item::get_id
item::get_item_from_revision
item::get_live_revision
item::get_mime_info
item::get_publish_status
item::get_revision_content
item::get_template_id
item::get_template_url
item::get_title
item::get_url
item::is_publishable
-Method Detail
-* indicates required
Public Methods:+ +
Method Detail
++* indicates required
+Public Methods: +
+item::content_is_null Determines if the content for the revision is null (not mereley zero-length)
-
@@ -25,7 +34,8 @@
- Returns:
- 1 if the content is null, 0 otherwise
+
+
-item::content_methods_by_type Determines all the valid content methods for instantiating a content type. Possible choices are text_entry, @@ -46,7 +56,8 @@
+
+item::get_best_revision Attempts to retrieve the live revision for the item. If no live revision exists, attempts to retrieve the latest revision. @@ -62,7 +73,8 @@
+
+item::get_content_type Retrieves the content type of tyhe item. If the item does not exist, returns an empty string.
-
@@ -76,7 +88,8 @@
item exists
+
+item::get_extended_url Retrieves the relative URL of the item with a file extension based on the item's mime_type (Example: { @@ -107,7 +120,8 @@
+
+item::get_id Looks up the URL and gets the item id at that URL, if any.
-
@@ -128,7 +142,8 @@
+
+item::get_item_from_revision Gets the item_id of the item to which the revision belongs.
-
@@ -142,7 +157,8 @@
+
+item::get_live_revision Retrieves the live revision for the item. If the item has no live revision, returns an empty string.
-
@@ -157,7 +173,8 @@
+
+item::get_mime_info Creates a onerow datasource in the calling frame which holds the mime_type and file_extension of the specified revision. @@ -181,7 +198,8 @@
+
+item::get_publish_status Get the publish status of the item. The publish status will be one of the following: @@ -207,7 +225,8 @@
+
+item::get_revision_content Create a onerow datasource called content in the calling frame which contains all attributes for the revision @@ -232,7 +251,8 @@
+
+item::get_template_id Retrieves the template which can be used to render the item. If there is a template registered directly to the item, @@ -256,7 +276,8 @@
+
+item::get_template_url Retrieves the relative URL of the template which can be used to render the item. The URL is relative to the TemplateRoot as @@ -278,7 +299,8 @@
+
+item::get_title Get the title for the item. If a live revision for the item exists, use the live revision. Otherwise, use the latest @@ -293,7 +315,8 @@
+
+item::get_url Retrieves the relative URL stub to th item. The URL is relative to the page root, and has no extension (Example: { @@ -309,7 +332,8 @@
+
+item::is_publishable Determine if the item is publishable. The item is publishable only if: @@ -327,6 +351,6 @@
- Returns:
- 1 if the item is publishable, 0 otherwise
+
* indicates required
- Index: openacs-4/packages/acs-templating/www/doc/TclDocs/namespace-list.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/namespace-list.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/TclDocs/namespace-list.adp 27 Oct 2014 16:40:17 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/namespace-list.adp 25 Aug 2015 18:02:12 -0000 1.2.2.1 @@ -2,16 +2,17 @@{/doc/acs-templating {Templating}} {} - - -All Namespaces
+Regenerate + these pages.doc
- doc::util
+All Namespaces +
+
Regenerate +doc
+ doc::util
form
request
util
-If you have not regenerated these pages before, you may have to reset permissions on all files to be written as well as your /doc/acs-templating/TclDocs directory.
- Index: openacs-4/packages/acs-templating/www/doc/TclDocs/namespaces.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/namespaces.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/TclDocs/namespaces.adp 27 Oct 2014 16:40:17 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/namespaces.adp 25 Aug 2015 18:02:12 -0000 1.2.2.1 @@ -2,11 +2,10 @@{/doc/acs-templating {Templating}} {} - - ATS and CMS Tcl Procedure -Specifications
-
Namespaces doc doc::util +Specifications + +
- Index: openacs-4/packages/acs-templating/www/doc/TclDocs/pagination.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/pagination.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/TclDocs/pagination.adp 27 Oct 2014 16:40:17 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/pagination.adp 25 Aug 2015 18:02:12 -0000 1.2.2.1 @@ -2,13 +2,20 @@Namespaces doc doc::util form Commands for managing dynamic templated forms.
@@ -21,4 +20,3 @@ util {/doc/acs-templating {Templating}} {} + Namespace pagination
+Procedures for paginating a datasource
+Method Summary
- -Namespace pagination
Procedures for paginating a datasource
Method Summary
-Listing of public methods:+Listing of public methods:
+pagination::get_total_pages
pagination::page_number_links
pagination::paginate_query
-Method Detail
-* indicates required
Public Methods:+ +
Method Detail
++* indicates required
+Public Methods: +
+
-pagination::get_total_pages
by Michael Pih@@ -21,7 +28,8 @@ +
+pagination::page_number_links
by Michael Pih@@ -40,7 +48,8 @@ +
+
-pagination::paginate_query
by Michael Pih@@ -58,11 +67,14 @@ +
Private Methods:
-+ +
pagination::get_rows_per_page Returns the number of rows per page
+
+
-pagination::ns_set_to_url_vars
by Michael Pih@@ -75,6 +87,6 @@ +
* indicates required
- Index: openacs-4/packages/acs-templating/www/doc/TclDocs/publish.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/publish.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/TclDocs/publish.adp 27 Oct 2014 16:40:17 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/publish.adp 25 Aug 2015 18:02:12 -0000 1.2.2.1 @@ -2,19 +2,29 @@{/doc/acs-templating {Templating}} {} - - Namespace publish
+ by Stanislav Freidin The procs in this namespace are useful for publishing items, including items inside other items, -and writing items to the filesystem.Specifically, the content, child and -relation tags are defined here.
Also see:
-
+and writing items to the filesystem.
+
- namespace
- item -
Specifically, the content, child and +relation tags are defined here.
+Also see:
+Method Summary
-Listing of public methods:+
Method Summary
+ +Listing of public methods:
+publish::get_html_body
publish::get_mime_handler
publish::get_page_root
publish::get_publish_roots
publish::get_template_root
publish::handle_binary_file
publish::item_include_tag
publish::mkdirs
publish::proc_exists
publish::publish_revision
publish::schedule_status_sweep
publish::set_publish_status
publish::unpublish_item
publish::unschedule_status_sweep
publish::write_content
-Method Detail
-* indicates required
Public Methods:+ +
Method Detail
++* indicates required
+Public Methods: +
+publish::get_html_body Strip the {<body>} tags from the HTML, leaving just the body itself. Useful for including templates in each @@ -29,7 +39,8 @@ if they exist; the unchanged HTML if they do not
+
+publish::get_mime_handler Return the name of a proc that should be used to render items with the given mime-type. The mime type handlers should all @@ -57,7 +68,8 @@
+
+publish::get_page_root Get the page root. All items will be published to the filesystem with their URLs relative to this root. The page root is @@ -68,7 +80,8 @@
+
+publish::get_publish_roots Get a list of all page roots to which files may be published. The publish roots are controlled by the PublishRoots @@ -79,7 +92,8 @@
+
+publish::get_template_root Get the template root. All templates are assumed to exist in the filesystem with their URLs relative to this root. The @@ -89,7 +103,8 @@
+
+publish::handle_binary_file Helper procedure for writing handlers for binary files. It will write the blob of the item to the filesystem, but only if @@ -141,11 +156,12 @@ order to prevent infinite recursion in the {<content>} tag. In this case, the proc will return the empty string { }
- See Also:
- proc - publish::handle::image
+- See Also:
- proc - publish::handle::image
-
+
+publish::item_include_tag Create an include tag to include an item, in the form
include src=/foo/bar/baz item_id=item_id @@ -168,7 +184,8 @@
+
+
-publish::mkdirs Create all the directories neccessary to save the specified file
- @@ -180,7 +197,8 @@
+
+publish::proc_exists Determine if a procedure exists in the given namespace
-
@@ -200,7 +218,8 @@
- Returns:
- 1 if the proc exists in the given namespace, 0 otherwise
+
+publish::publish_revision Render a revision for an item and write it to the filesystem. The revision is always rendered with the @@ -219,7 +238,8 @@
+
+publish::schedule_status_sweep Schedule a proc to keep track of the publish status. Resets the publish status to { expired} if the expiration date has @@ -240,7 +260,8 @@
+
+publish::set_publish_status Set the publish status of the item. If the status is live, publish the live revision of the item to the filesystem. @@ -270,7 +291,8 @@
+
+publish::unpublish_item Delete files which were created by publish_revision @@ -295,15 +317,17 @@
+
+publish::unschedule_status_sweep Unschedule the proc which keeps track of the publish status.
- See Also:
- proc - publish::schedule_status_sweep
+
+publish::write_content Write the content (blob) of a revision into a binary file in the filesystem. The file will be published at the relative @@ -339,9 +363,11 @@
+ +
Private Methods:
-+ +
publish::delete_multiple_files Delete the specified URL from the filesystem, for all revisions
-
@@ -355,7 +381,8 @@
+
+publish::foreach_publish_path Execute some Tcl code for each root path in the PublishRoots parameter
-
@@ -379,23 +406,26 @@
+
+publish::get_main_item_id Get the main item id from the top of the stack
- Returns:
- the main item id
- See Also:
- proc - publish::get_main_revision_id
publish::pop_id
publish::push_id
+
+publish::get_main_revision_id Get the main item revision from the top of the stack
- Returns:
- the main item id
- See Also:
- proc - publish::get_main_item_id
publish::pop_id
publish::push_id
+
+publish::handle_item Render an item either by looking it up in the the temporary cache, or by using the appropriate mime handler. Once the @@ -438,11 +468,12 @@
htmlExtra HTML parameters to be passed to the item handler, in format {name value name value ...} - See Also:
- proc - publish::handle::image
publish::handle::text
publish::handle_binary_file
+- See Also:
- proc - publish::handle::image
-
publish::handle::text
publish::handle_binary_file
+
+publish::html_args Concatenate a list of name-value pairs as returned by set_to_pairs into a list of { name=value} @@ -457,7 +488,8 @@
+
+publish::merge_with_template Merge the item with its template and return the resulting HTML. This proc is simlar to @@ -482,7 +514,8 @@
+
+publish::pop_id Pop the item_id and the revision_id off the top of the stack. Clear the temporary item cache if the stack becomes @@ -492,7 +525,8 @@
+
+publish::process_tag Process a child or relation tag. This is a helper proc for the tags, which acts as a wrapper for @@ -514,7 +548,8 @@
+
+publish::push_id Push an item id on top of stack. This proc is used to store state between child, relation and @@ -535,7 +570,8 @@
+
+publish::render_subitem Render a child/related item and return the resulting HTML, stripping off the headers.
-
@@ -588,7 +624,8 @@
+
+publish::set_to_pairs Convert an ns_set into a list of name-value pairs, in form {name value name value ...}
-
@@ -608,15 +645,17 @@
ns_set
+
+publish::track_publish_status Scheduled proc which keeps the publish status updated
- See Also:
- proc - publish::schedule_status_sweep
+
+publish::write_multiple_blobs Write the content of some revision to multiple publishing roots.
-
@@ -640,7 +679,8 @@
+
+
-publish::write_multiple_files Write a relative URL to the multiple publishing roots.
-
@@ -656,11 +696,12 @@
A string of text to be written to the URL - See Also:
- proc - publish::get_publish_roots
publish::write_multiple_blobs
template::util::write_file
+- See Also:
- proc - publish::get_publish_roots
-
publish::write_multiple_blobs
template::util::write_file
+
+
-Implements the child tag which renders a child item. See the Developer Guide for more information.
@@ -675,7 +716,8 @@+
+
-Implements the content tag which renders the content of the current item. See the Developer Guide for more @@ -690,7 +732,8 @@
+
+
-Implements the relation tag which renders a related item. See the Developer Guide for more information.
@@ -705,6 +748,6 @@+ +
* indicates required
- Index: openacs-4/packages/acs-templating/www/doc/TclDocs/request.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/request.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/TclDocs/request.adp 27 Oct 2014 16:40:17 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/request.adp 25 Aug 2015 18:02:12 -0000 1.2.2.1 @@ -2,20 +2,29 @@{/doc/acs-templating {Templating}} {} - - - Namespace request
The request commands provide a mechanism for managing +
+Namespace request
+The request commands provide a mechanism for managing the query parameters to a page. The request is simply a special instance of a form object, and is useful for the frequent cases when data must be passed from page to page to determine display or page flow, rather than perform a transaction based on user input -via a form.
Also see:
-
+via a form.
Also see:
+- form
- element -
Method Summary
-Listing of public methods:+ +
Method Summary
+ +Listing of public methods:
+
-Method Detail
-* indicates required
Public Methods:+ +
Method Detail
++* indicates required
+Public Methods: +
+Checks for any param errors. If errors are found, sets the display template to the specified URL (a system-wide request @@ -32,7 +41,8 @@
- Returns:
- 1 if no error conditions exist, 0 otherwise.
+
+
-Create the request data structure. Typically called at the beginning of the code for any page that accepts query @@ -44,7 +54,8 @@
+
+Declares a query parameter as part of the page request. Validates the values associated with the parameter, in the same @@ -82,7 +93,8 @@
+
+
-Manually report request error(s) by setting error messages and then calling is_valid to handle display. Useful for @@ -104,7 +116,8 @@
+
+Retrieves the value(s) of the specified parameter.
-
@@ -117,6 +130,6 @@
- Returns:
- The value of the specified parameter.
+ +
* indicates required
- Index: openacs-4/packages/acs-templating/www/doc/TclDocs/tcl-procs.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/tcl-procs.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/TclDocs/tcl-procs.adp 27 Oct 2014 16:40:18 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/tcl-procs.adp 25 Aug 2015 18:02:13 -0000 1.2.2.1 @@ -4,5 +4,3 @@ArsDigita Templating System, Content Management Tcl Procedure Specifications - - Index: openacs-4/packages/acs-templating/www/doc/TclDocs/util.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/util.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/TclDocs/util.adp 27 Oct 2014 16:40:18 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/util.adp 25 Aug 2015 18:02:13 -0000 1.2.2.1 @@ -2,23 +2,30 @@ {/doc/acs-templating {Templating}} {} + Namespace util
+Method Summary
- -Namespace util
Method Summary
-Listing of public methods:The namespace util currently contains no public -methods.
Method Detail
-* indicates required
+Listing of public methods:
+The namespace util currently contains no public +methods.
+Method Detail
++* indicates required
+Private Methods:
-+ +
a proc used for debugging, just prints out a value to the error log
+
+capitalizes the first letter of a string
- Returns:
- returns formatted string
+
+escapes quotes and removes comment tags from a body of commented text
-
@@ -31,7 +38,8 @@
- Returns:
- text
+
+just takes a body of text and puts a space behind every double {quote;} this is done so that the text body can be treated @@ -47,7 +55,8 @@ that are already trailed by a space are unaffected
+
+
-takes a .adp template name and the name of the file to be written and creates the {file;} also puts out a notice @@ -66,7 +75,8 @@
+
+takes an alphabetized list and an entry
- @@ -86,15 +96,18 @@ -1 if the entry is already in the list
+
+used to compare two different elements in a list of parsed data for public or private procs
+
+uses ns_library to find the server root, may not always be accurate because it essentially asks for the tcl library path and strips off the last /tcl directory
+
++ +
* indicates required
- Index: openacs-4/packages/acs-templating/www/doc/TclDocs/widget.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/widget.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/TclDocs/widget.adp 27 Oct 2014 16:40:18 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/widget.adp 25 Aug 2015 18:02:13 -0000 1.2.2.1 @@ -2,14 +2,21 @@{/doc/acs-templating {Templating}} {} + Namespace widget
+Procedures for generating and processing metadata form +widgets, editing attribute widgets
+Method Summary
- -Namespace widget
Procedures for generating and processing metadata form -widgets, editing attribute widgets
Method Summary
-Listing of public methods:+Listing of public methods:
+widget::param_element_create
-Method Detail
-* indicates required
Public Methods:+ +
Method Detail
++* indicates required
+Public Methods: +
+
-widget::param_element_create Dipatches subprocs to generate the form elements for setting an attribute widget param
- @@ -51,9 +58,11 @@
+ +
Private Methods:
-+ +
-widget::create_options_param
by Michael Pih@@ -88,7 +97,8 @@ +
+
-widget::create_param_source
by Michael Pih@@ -113,7 +123,8 @@ +
+
-widget::create_param_type
by Michael Pih@@ -133,7 +144,8 @@ +
+
-widget::create_param_value
by Michael Pih@@ -158,7 +170,8 @@ +
+
-widget::create_text_param
by Michael Pih@@ -188,7 +201,8 @@ +
+
-widget::create_values_param
by Michael Pih@@ -223,7 +237,8 @@ +
+
-widget::process_param
by Michael Pih@@ -256,6 +271,6 @@ + +
* indicates required
- Index: openacs-4/packages/acs-templating/www/doc/api/database.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/api/database.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/api/database.adp 27 Oct 2014 16:40:18 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/api/database.adp 25 Aug 2015 18:02:13 -0000 1.2.2.1 @@ -2,16 +2,21 @@{/doc/acs-templating {Templating}} {Templating System API: Database Query} Templating System API: Database Query - - - Database Query
Summary
Utilize the results of a database query as a template data -source.
Method
+
Database Query
+Summary
+Utilize the results of a database query as a template data +source.
+Method
+query name structure sql -db dbhandle -startrow n -maxrows n -bind (set|list) -eval { code } -Perform a query and store the results in a local variable.
Examples
+
+Perform a query and store the results in a local variable.
+Examples
+set db [ns_db gethandle] # this will set a scalar named current_time @@ -38,7 +43,9 @@ template::query persons nestedlist " select state, city, first_name, last_name from users" \ -db $db -groupby { state city } -Note(s)
-
+
- Valid values for structure are onevalue, onerow, multirow, onelist, nestedlist and multilist.
- @@ -52,5 +59,6 @@ perform on each row of a multirow query as it is fetched from the database. The code may refer to the row array to get and set column values.
- The bind option is valid only when using Oracle. -
The simple answer is that the content repository (CR) gives you +many different things for free:
+State of this document
+ This is not a perfect introduction to the content repository. But hopefully it will be a skeleton that can be developed further into an excellent, helpful tutorial for people new to the content repository. -Introduction
For the sake of an example, I'm going to use a Tasks +
Introduction
+For the sake of an example, I'm going to use a Tasks application. This application will keep track of all the tasks of an organization, deadlines for those tasks, and who needs to work -on them.
The reason I might be interested in using the content repository +on them.
+The reason I might be interested in using the content repository (CR) in this case is that I can keep track of all the changes to a particular Task, so that if someone changes the deadline on an item, I can see what the original deadline was. In addition, I as a developer would like to have sub-tasks, and sub-sub-tasks, so I can have a whole hierarchy of things that need to be accomplished. Big tasks can be sub-divided so that several people can each do their -particular parts.
So I decide to create a Tasks table. Each of these Tasks has +particular parts.
+So I decide to create a Tasks table. Each of these Tasks has various information associated with it, such as deadlines, -descriptions of what needs to be accomplished, and so on:
++descriptions of what needs to be accomplished, and so on: +Task Title Description Task Number -Overview
First of all, let's get some terminology out of the way. Columns +
Overview
+First of all, let's get some terminology out of the way. Columns of a table are referred to as attributes in content repository-speak.
+ The steps to set up your data model are as follows:What attributes do you want?
The first step is to decide on what part of a Task you'd you'd + +
What attributes do you want?
+The first step is to decide on what part of a Task you'd you'd like to have under revision control, and what portion you'd like to have just one version of. In our case, the only thing we wouldn't want under version control is the Task Number. This will be a unique identifier for the task, and we don't want that changing -every time someone edits it.
For our simple example:
++every time someone edits it. +For our simple example:
+Title - want versions Description - want versions Task Number - do NOT want versions -Define tables
You will have two tables: one with versioned attributes, and one -without versioned attributes.
+
Define tables
+You will have two tables: one with versioned attributes, and one +without versioned attributes.
+Convention: often, developers will name the first table by what it is (in my case pm_tasks), and the second, versioned table by the same name, but with _revisions at the end. Thus, I'll name my second table pm_tasks_revisions.
+ This is actually very easy: -Versioned portion:
++Versioned portion:
+create table pm_tasks_revisions ( task_revision_id integer @@ -77,7 +98,9 @@ varchar(4000) ); -Unversioned portion:
++Unversioned portion:
+create table pm_tasks ( task_id integer @@ -90,27 +113,34 @@ integer ) -One thing you have to be careful of when creating these tables +
One thing you have to be careful of when creating these tables
is that there are no columns that have the same names as any of the
columns in the cr_items and cr_revisions
tables. For example, you can't call you key on the
pm_tasks_revisions table revision_id. Why? There are
some views that are automatically generated that combine these
tables for you, but they won't be created if the names conflict.
I'll describe what these views are later, but they are useful. You
-were warned.
Notice that each table uses as its primary key a reference to +were warned.
+Notice that each table uses as its primary key a reference to
either the cr_revisions table or the
cr_items table. A content item is basically
just some content: either text or binary data. The contents
revisions table keeps track of which version from the
tasks_revisions table is the most current, and which one is
-live.
All this is going inside the +live.
+All this is going inside the
sql/postgresql/project-manager-create.sql file. Your
-name will be different of course.
Describe attributes
After we've created the two tables, we need to let the content +name will be different of course.
+Describe attributes
+After we've created the two tables, we need to let the content repository know that we have a new type of structured data that we are storing in the content repository. Tasks are a "content type", because they have data associated with them, such as when they are -due, and what needs to be done.
I thus need to to
++due, and what needs to be done. +I thus need to to
+--create the content type select content_type__create_type ( 'pm_task', -- content_type @@ -122,10 +152,12 @@ 'content_revision.revision_name' ); -You then need to add in all the attributes, so that the content +
You then need to add in all the attributes, so that the content repository can do some magic things behind the scenes. The content repository doesn't know about what's inside of the pm_tasks -and pm_tasks_revisions tables, so we teach it:
++and pm_tasks_revisions tables, so we teach it: +-- add in attributes select content_type__create_attribute ( @@ -161,17 +193,21 @@ 'numeric' -- column_spec ); -+
Side effect: once you've created the content type, the
content repository creates a view for you called
pm_tasks_revisionsx. Note the x at the end of the
name. If you're using Postgres, I believe it will also create a
view for you called pm_tasks_revisionsi
-
Why are these two views created? the x view is created for +
+Why are these two views created? the x view is created for selection, and the i view is created for inserts. They join the acs_objects, cr_revisions, and our pm_tasks_revisions tables together. Try viewing them to get an idea of how they might be -useful.
Advanced topic: Creating types and attributes
It is also possible to dynamically create tables, and extend +useful.
+Advanced topic: Creating types and attributes
+It is also possible to dynamically create tables, and extend
them with extra columns. You could do this by using create
table or alter table add column statements in
SQL, but this also adds in some meta-data that will be useful to
@@ -180,12 +216,14 @@
really cool stuff with it, like automatically generate interfaces
that take advantage of the new columns and tables you've added.
Another nice thing is that all that messy business of defining your
-attributes through the API is taken care of.
+attributes through the API is taken care of.
+
Types is the content repository are another term for
tables, although that doesn't explain it completely. Types are also
kept track of within OpenACS, in the acs_object_types
table, so the system knows about the tables you create, and can do
-some intelligent things with them.
A lot of the intelligent things you can do with this +some intelligent things with them.
+A lot of the intelligent things you can do with this information is still being built. But imagine for example that you are using the project manager package I've written. You work at an ice cream company, and every task that is done also has an @@ -196,24 +234,29 @@ automatically taken care of. You'll be able to select a flavor when you edit a task, and it will be shown on the task view page. This is the direction OpenACS development is going, and it will be -really really cool!
First, I'm going to describe how to extend other content +really really cool!
+First, I'm going to describe how to extend other content repository tables using the CR API. Then, I'll describe how to set -up your own tables as well:
As you recall from earlier in this page, attributes are just +up your own tables as well:
+As you recall from earlier in this page, attributes are just
another term for columns in a table. The Content Repository has a
mechanism for adding and removing columns via the pl/sql API. If
you check your /api-doc:
/api-doc/plsql-subprogram-one?type=FUNCTION&name=content%5ftype%5f%5fcreate%5fattribute
, you'll see that there is a way to extend the columns
-programmatically.
Why would you want to do this? For project manager, I decided to +programmatically.
+Why would you want to do this? For project manager, I decided to do this because I wanted to customize my local version of the projects table, to account for company-specific information. That way, I can have a separate edit page for those types, but not have a separate table to join against.
+ . Instead of doing this:
alter table pm_projects add column
target_date date;
select content_type__create_attribute(
@@ -227,6 +270,7 @@
'date'
);
How versioning works
+ You then need to define a couple of functions, that do all the nasty work of putting everything in the right tables. The general idea behind it is that the revisioned information is never changed, but added to. Here's how it works. When you create a new task, you -call thepm_task__new_task_item function (which we'll
+call the pm_task__new_task_item
+ function (which we'll
write in a little bit). This function creates both a new content
item, and a new content revision. Information is actually stored in
-four tables, believe it or not: cr_revisions,
-cr_items, pm_tasks, and
-pm_tasks_revisions. The task number is stored in
+four tables, believe it or not: cr_revisions
+,
+cr_items
+, pm_tasks
+, and
+pm_tasks_revisions
+. The task number is stored in
pm_tasks, the title and description are stored in
pm_tasks_revisions, and some additional information like who
entered the information is stored in cr_revisions and cr_items.
Whenever you make a change to this item, you don't change the table
-yourself, but add a revision, using your
-pm_task__new_task_revision function (which we'll write
+yourself, but add
+ a revision, using your
+pm_task__new_task_revision
+ function (which we'll write
in a little bit). This function adds another revision, but
-not another item or cr_item. After you've added another
+not
+ another item or cr_item. After you've added another
revision, you'll have two revisions and one item. Two entries in
cr_revisions (and pm_tasks_revisions), and one item in cr_items and
pm_tasks. The cr_revisions table keeps track of which item is the
@@ -278,9 +333,11 @@
pm_tasks_revisions table with the cr_revisions table (and it might
even join in cr_items -- I forget at the moment).
Defining your pl/sql functions
+ You can see the actual functions used in project manager via the -CVS browser's entry for project-manager. Note these are a +CVS browser's entry for project-manager +. Note these are a little more expanded than what I've used in the examples above.
select define_function_args('pm_task__new_task_item', 'task_id, project_id, title, description, end_date, percent_complete, estimated_hours_work, estimated_hours_work_min, estimated_hours_work_max, creation_date, creation_user, creation_ip, package_id');
@@ -447,7 +504,9 @@
return 0;
end;
$$ language plpgsql;
-Explanation of the columns in cr_items and cr_revisions
+ +Explanation of the columns in cr_items and cr_revisions
+ cr_items:item_id - unique id for this item, will be @@ -461,6 +520,7 @@ revision_id that is the latest version+ cr_revisions:
publish_status - not sure
content_type - not sure
storage_type - not sure, probably text or binary?
storage_area_key - not sure
tree_sortkey - a utility column used in hierarchical queries.
revision_id - a unique id for this revision.
item_id - a reference to the item_id for this revision
title - you can use this for your application. For example, @@ -469,7 +529,9 @@ is for your use, or internal
mime_type - the mime type.
nls_language - I believe this is for internationalization
lob - the binary content.
content - the text content.
content_length - the length of the text or binary content?
-
Structuring your data into a hierarchy
+ +Structuring your data into a hierarchy
+ The content repository also has a very useful facility for organizing your data into a hierarchy, very similar to a file-system. Just like a file system, you can have folders to store @@ -480,10 +542,12 @@ project-management software, this also allows my tasks to be stored underneath their given project.Using this structure is optional, but useful in many -circumstances.
The facility for this is built into the cr_items
+circumstances.
The facility for this is built into the cr_items
data model. This makes sense, because you wouldn't want your
hierarchy associated with each revision. Here's how Postgres
-describes the cr_items table:
+describes the+cr_itemstable: +-TheTable "public.cr_items" Column | Type | Modifiers ------------------+------------------------+----------------------------- @@ -499,10 +563,15 @@ storage_area_key | character varying(100) | not null default 'CR_FILES' tree_sortkey | bit varying |parent_idrefers to either a content item -(cr_items), or a subclass of a content_item (such as -cr_folders). I'll explain more later about -cr_folders. + +Theparent_id+ refers to either a content item +(cr_items+), or a subclass of a content_item (such as +cr_folders+). I'll explain more later about +cr_folders+.One thing that you might want to do for your application is to give the application its own root directory. Because the content repository is shared among applications, this separates it off from @@ -516,7 +585,8 @@ your own root repository is that you application may be mounted several times. If you want to separate the directory structure between instances of your application, you need to create your own -root directory:
+root directory: ++ Note that this example is for projects rather than tasks. This is because for the application I'm writing, projects are what tasks are stored inside of. A project has many component tasks. If you @@ -582,32 +653,39 @@-- Creates and returns a unique name for new project folders select define_function_args('pm_project__new_unique_name', 'package_id'); @@ -574,6 +644,7 @@ end; $$ language plpgsql;Typically, this definition would go in your
sql/postgresql/project-manager-create.sqlfile. If this file is broken in several parts, this would go in the -project-manager-create-functions.sql portion.Once you've created your root directory, you will set the +project-manager-create-functions.sql portion.
+Once you've created your root directory, you will set the
parent_idof your items to the id for the new root repository (in our case, it's returned from the -pm_project__new_root_folder function)In the project-manager application, we'll create a root +
+pm_project__new_root_folder function)In the project-manager application, we'll create a root repository, and make all projects under that root repository. That means they'll all have a
parent_idset to the root repository. However, we also want to make projects that are sub-projects of other projects. In that case, we will set theparent_idof the sub-project to the -item_idof the parent.Understanding folders
+item_idof the parent. +Understanding folders
+ For a little while now, we have been talking about folders, but we haven't delved into what CR folders are. Folders are sub-classes of -cr_items, and the only real difference is that they +cr_items+, and the only real difference is that they contain no data, except for a label and description.If you create folders for your application, then you'll need to make sure you manage them along with your other objects. For example, if you were to add a folder for each of your objects, then you would probably want to make sure you delete the folder when you -delete the object.
However, in many cases you are not creating more than one +delete the object.
+However, in many cases you are not creating more than one folder. In fact, the only folder you might have will be the root folder you create for each instance of your application (if you install the project-manager in two parts of your web server, for example, it should have two different root folders). When your application is running, it can determine the root folder by searching the cr_folders table. Here's the definition of that -table:
++table: +-Note that there is aTable "public.cr_folders" Column | Type | Modifiers --------------------+-------------------------+------------- @@ -618,22 +696,30 @@ has_child_symlinks | boolean | default 'f' package_id | integer |package_idcolumn. The nice thing + +Note that there is apackage_id+ column. The nice thing about this column is that you can use it to find the root repository, if you only have one folder per instance of your application. You can get your package_id using this call within your .tcl file:+ Then you can find the root repository by using a query like this:set package_id [ad_conn package_id]select folder_id from cr_folders where package_id = :package_id; -Create scripts
Drop scripts
+Create scripts
+Drop scripts
+ If you have problems with your drop script in OpenACS 4.6.2, then Tammy's -drop scripts might be of interest to you. +drop scripts + might be of interest to you.Using your data model
+ You now have a shiny new data model that handles revisions and all sorts of other things we haven't gotten to yet. Now, in your Tcl pages and your ps/sql code, you can... @@ -645,71 +731,92 @@Get latest revision (pl/sql) live_revision_id := content_item__get_live_revision(:item_id); -The item_id identifies the content item with which the revision -is associated.
Likewise, the most recent revision of a content item can be -obtained with the content_item__get_latest_revision function
Reference:
+ +
+The item_id identifies the content item with which the revision +is associated.
+Likewise, the most recent revision of a content item can be +obtained with the content_item__get_latest_revision function
+Reference:
+Reference: Definitions
+
Reference: Definitions
+
+
+
+
+
+
+
+
+
+
+
Content templates
+ +Content templates
+ The only place content templates are used in OpenACS are in the 5.0 version of file storage. See CR and -content_template defined wrongTroubleshooting
+content_template defined wrong +Troubleshooting
+ One problem I ran into while trying to get my SQL create and drop scripts working was that sometimes I wasn't able to delete a content type because I would get errors like these:+ The problem seems to be that there were still items in the -Referential Integrity: attempting to delete live_revision: 658cr_itemstable. You can remove them usingselect -content_item__delete(648);in psql. You get the codes by +cr_items+ table. You can remove them usingselect +content_item__delete(648);+ in psql. You get the codes by doing a query like this:+ Really, however, what you need to do is make sure your __delete and drop scripts first go through and delete all children of those items. I'm not sure if you need to delete the items themselves -- I believe they may be dropped by themselves when the tables are -dropped, because of theselect i.item_id, r.revision_id, r.title, i.content_type from cr_items i, cr_revisions r where i.item_id = r.item_id order by i.item_id, r.revision_id;cascadeportion of the SQL +dropped, because of thecascade+ portion of the SQL data model.When I was troubleshooting folders, I found this query -useful:
++useful: +select f.folder_id,f.label,f.description,i.content_type from cr_folders f, cr_items i where f.folder_id = i.item_id; -Once again, thanks to daveb for help in tracking this down (he +
Once again, thanks to daveb for help in tracking this down (he rocks!).
- Index: openacs-4/packages/acs-content-repository/www/doc/uninstall.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/uninstall.adp,v diff -u -N -r1.2.2.1 -r1.2.2.2 --- openacs-4/packages/acs-content-repository/www/doc/uninstall.adp 20 Aug 2015 17:19:49 -0000 1.2.2.1 +++ openacs-4/packages/acs-content-repository/www/doc/uninstall.adp 25 Aug 2015 18:02:02 -0000 1.2.2.2 @@ -2,26 +2,32 @@{/doc/acs-content-repository {Content Repository}} {Content Repository: Uninstalling} Content Repository: Uninstalling - - - Uninstalling the Content Repository
The content repository includes an uninstall script, -sql/content-drop.sql. This script does two things:
+
+Uninstalling the 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:
+
+The uninstall script does not do the following:
+
Because of what the uninstall script does not do, it is +
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 entire data model. +
+karlg\@arsdigita.com +
+ Last revised: $Id: uninstall.html,v 1.1.1.1 2001/03/13 22:59:26 ben Exp $ - Index: openacs-4/packages/acs-content-repository/www/doc/api/content.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/api/content.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-content-repository/www/doc/api/content.adp 27 Oct 2014 16:39:13 -0000 1.2 +++ openacs-4/packages/acs-content-repository/www/doc/api/content.adp 25 Aug 2015 18:02:02 -0000 1.2.2.1 @@ -2,10 +2,12 @@{/doc/acs-content-repository {Content Repository}} {Package: content} Package: content - - - content
-Content Repository : content
+
+content
++Content Repository : content
+
++
Parameters: Not yet documented Declaration: - function blob_to_string( blob_loc blob) return varchar2 @@ -17,7 +19,9 @@ ) return java.lang.String';
+
++
Parameters: Not yet documented Declaration: -
+
++
Parameters: Not yet documented Declaration: - procedure string_to_blob( s varchar2, blob_loc blob) @@ -41,7 +47,9 @@ )';
+
++
Parameters: Not yet documented Declaration: - procedure string_to_blob_size( s varchar2, blob_loc blob, blob_size number) @@ -53,6 +61,6 @@ )';Last Modified: $Id: content.html,v 1.1.1.1 2001/03/13 22:59:26 +
Last Modified: $Id: content.html,v 1.1.1.1 2001/03/13 22:59:26 ben Exp $
- Index: openacs-4/packages/acs-content-repository/www/doc/api/extlink.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/api/extlink.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-content-repository/www/doc/api/extlink.adp 27 Oct 2014 16:39:13 -0000 1.2 +++ openacs-4/packages/acs-content-repository/www/doc/api/extlink.adp 25 Aug 2015 18:02:03 -0000 1.2.2.1 @@ -2,21 +2,32 @@{/doc/acs-content-repository {Content Repository}} {Package: content_extlink} Package: content_extlink - - - content_extlink
+
content_extlink
+Content Repository : -content_extlink
+content_extlink +
+
+
Overview
External links are references to content pages on other web +
+
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
+keywords and related to the site's own content items. ++
Related Objects
+ See also: {content_item } -
API
Note(s)
+
templating\@arsdigita.com - +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/api/element.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/api/element.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/api/element.adp 27 Oct 2014 16:40:18 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/api/element.adp 25 Aug 2015 18:02:13 -0000 1.2.2.1 @@ -2,9 +2,10 @@
Form Element
Summary
Methods
+Form Element
+Summary
+Methods
+template::element create form_name element_name \ -widget widget \ -datatype datatype \ @@ -18,7 +19,9 @@ -value value \ -values { value value ... } -Append a new element to the specified form.
-
+
+
- The html switch may be used to include additional HTML attributes in the input, select, or textarea tag used to ultimately render the element.
- The validate switch may be used to perform simple @@ -34,12 +37,18 @@ $value and $label may be used in the message to reference the parameter value and label (or name if no label is supplied). -
Append a new element to the specified form.
++ ++template::element set_properties form_name element_name -++template::element get_value form_name element_name -Example
++Example
+template::element get_values form_name element_name -Note(s)
templating\@arsdigita.com - +
Note(s)
++templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/api/form.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/api/form.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/api/form.adp 27 Oct 2014 16:40:18 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/api/form.adp 25 Aug 2015 18:02:13 -0000 1.2.2.1 @@ -2,24 +2,35 @@
Form
Summary
Building dynamic forms with automated validation.
Methods
+Form
+Summary
+Building dynamic forms with automated validation.
+Methods
+template::form create name \ -html { attribute value attribute value } -Initialize data structures for a dynamic form. This procedure -must be called before adding elements to the form.
- Additional attributes to include in the HTML form tag may be -specified with the html option.
++
Initialize data structures for a dynamic form. This procedure +must be called before adding elements to the form.
+- Additional attributes to include in the HTML form tag may be +specified with the html option.
template::form is_request name -
Boolean procedure for determining whether a submission is in + +
Boolean procedure for determining whether a submission is in progress. If this procedure returns true, then an initial request for the form is underway. The code for insert or add forms may thus query for primary key value(s), and the code for update forms may query for current data and set the value(s) of form elements -accordingly.
+accordingly. ++template::form is_valid name -Boolean procedure that returns true if a submission is in +
Boolean procedure that returns true if a submission is in progress and the submission is valid. Database or any other transactions based on the form submission should only take -place after this procedure has been checked.
Example
Note(s)
templating\@arsdigita.com - +place after this procedure has been checked. +
Example
+Note(s)
++templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/api/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/api/index.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/api/index.adp 27 Oct 2014 16:40:18 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/api/index.adp 25 Aug 2015 18:02:13 -0000 1.2.2.1 @@ -2,19 +2,24 @@
Object and API Reference
+Templating System + : Developer Guide + : API - -Object and API Reference
Templating System : Developer Guide : API - Some of the API discussed here achieves functionality that the ACS (ArsDigita Community System) provides, just in different ways. If you have the ACS installed, you likely want to use that instead of -thequery and request call presented
+the query
+ and request
+ call presented
below.
Christian -Brechbühler + +
+Christian +Brechbühler + Last modified: $Id: index.html,v 1.1.1.1 2001/03/13 22:59:27 ben Exp $ - Index: openacs-4/packages/acs-templating/www/doc/api/multirow.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/api/multirow.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/api/multirow.adp 27 Oct 2014 16:40:18 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/api/multirow.adp 25 Aug 2015 18:02:13 -0000 1.2.2.1 @@ -2,35 +2,50 @@
Multirow
Summary
Access and modify rows and columns of a multirow data -source.
Methods
++Multirow
+Summary
+Access and modify rows and columns of a multirow data +source.
+Methods
+multirow getname index column -+
Get a particular column value or a reference to an entire row.
-
- Rows are indexed starting with 1.
- If a column name is omitted, this procedure will set name to be a reference to an array containing the values for the row specified by index.
+ ++multirow setname index column value -Set the value of a column in a specified row.
+++Set the value of a column in a specified row.
multirow sizename -Get the number of rows in the data source.
+++Get the number of rows in the data source.
multirow createname column [column ...] -Set up a new multirow data source. This is an alternative to +
Set up a new multirow data source. This is an alternative to having db_multirow create the -data source.
+data source. ++multirow appendname value [value ...] -Add a row at the end of the data source. Extra values are -dropped, missing values default to the empty string
+++Add a row at the end of the data source. Extra values are +dropped, missing values default to the empty string
multirow mapname body -Evaluate body for each row of the data source, and +
Evaluate body for each row of the data source, and return a list with all results. Within the body, all columns of the current row are accessible (and modifiable) as local variables. -(Not yet committed.)
Examples
+(Not yet committed.) +Examples
+template::query foo multirow "select first_name, last_name from users" # get the first name of the first user @@ -41,7 +56,10 @@ # this will the full name of the first user set full_name "$foo(first_name) $foo(last_name)" -Note(s)
- Use the eval option to template::query to modify
+
+
Note(s)
+- Use the eval option to template::query to modify column values while building a data source from a multirow query -result.
templating\@arsdigita.com - +result.
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/api/request.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/api/request.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/api/request.adp 27 Oct 2014 16:40:18 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/api/request.adp 25 Aug 2015 18:02:13 -0000 1.2.2.1 @@ -2,24 +2,31 @@
Page Request
Summary
Transform, validate and report errors in the query parameters -associated with a page request.
This API is an alternative to ad_page_contract
-which should usually be preferred if you have ACS installed.
Methods
++Page Request
+Summary
+Transform, validate and report errors in the query parameters +associated with a page request.
+This API is an alternative to
+ad_page_contract+which should usually be preferred if you have ACS installed.Methods
+template::request create -Initialize the data structure to store request parameters. +
Initialize the data structure to store request parameters. Should be called at the start of any page that takes request -parameters.
+parameters. ++template::request set_param name -datatype datatype -multiple -optional -validate { { expression } { message } } -Validates request parameter values and then sets a local +
Validates request parameter values and then sets a local variable. Values are transformed if a transformation procedure exists for the specified datatype (i.e. the components of a -date are assembled into a single structure).
-
+date are assembled into a single structure).
+
- Options for datatype are the same as for form elements.
- The multiple switch indicates that more than one value may be submitted. The local variable set by the procedure will be a @@ -34,18 +41,25 @@ validation fails. The variables $value and $label may be used in the message to reference the parameter value and label (or name if no label is supplied). -
+ +template::request get_param name -Returns the value (or values if the multiple is used) -of the named parameter.
++Returns the value (or values if the multiple is used) +of the named parameter.
+template::request is_valid error_url -Boolean procedure for determining whether any validation errors -occurred while setting request parameters.
-
+
+
Boolean procedure for determining whether any validation errors +occurred while setting request parameters.
+- error_url is the location of the template to use for reporting request errors. The default is /ats/templates/messages/request-error if no URL is specified. To report request errors in the template of the page -itself, use self for the URL.
Example
+itself, use self for the URL.
Example
+
request create
request set_param state_abbrev -datatype keyword -validate {
@@ -59,12 +73,15 @@
if { ! [request is_valid "/mytemplates/request-error"] } { return }
...
-Note(s)
-
+
+
- Error reporting templates may reference the requesterror array to access error messages for each parameter.
- The request API provides a simple mechanism for processing request parameters. It is not intended as a replacement to ad_page_contract for sites built on the ArsDigita Community System. -
Note(s)
+templating\@arsdigita.com - +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/appendices/memory.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/appendices/memory.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/appendices/memory.adp 27 Oct 2014 16:40:18 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/appendices/memory.adp 25 Aug 2015 18:02:13 -0000 1.2.2.1 @@ -4,18 +4,21 @@
Parsing Templates in Memory
The templating system code is oriented towards parsing templates +
Parsing Templates in Memory
+The templating system code is oriented towards parsing templates stored in the file system, in conjunction with a Tcl script that is also stored as a file. However, when the template is not actually stored in the file system, you will need to parse it as a string in -memory. Two common situations in which this occurs are:
-
+memory. Two common situations in which this occurs are:
+
- Templates are stored in the database.
- Templates are generated dynamically, possibly based in turn on a "style" template. This is how ATS auto-generates forms. -
The Parsing Process
Whether the template is ultimately stored in a file or not, the +
The Parsing Process
+Whether the template is ultimately stored in a file or not, the templating system follows the same basic process during the parsing -process:
-
+process:
+
- Prepare data sources. Some Tcl code is evaluated to prepare data sources (scalars, lists, multirow data structures) for @@ -31,9 +34,12 @@ all variables declared as data sources are directly available to the template. The result of the evaluation step is a single string, which normally is written to the connection. -
How to Parse Templates in Memory
The templating system provides a low-level API that allows you +
How to Parse Templates in Memory
+The templating system provides a low-level API that allows you to perform the three steps described above in the context of your -own code:
+ Note that comment lines are indented to indicate the manner in which they should be grouped only, and that there is no required spacing scheme for comments.+own code: +-Also see the "string" demo. -# set up any number of data sources: set first_name George @@ -68,8 +74,11 @@ # now use the output however you wishGenerating Templates from Other Templates
In some cases, the template itself may be based on yet another + +Also see the "string +" demo. +
Generating Templates from Other Templates
+In some cases, the template itself may be based on yet another base template. For example, the templating system itself generates form templates based on a generic "style" template. The generic template primarily depends on a single data source, @@ -78,11 +87,15 @@ lay out the specific formwidget and formgroup tags, along with labels and validation text, for the form. The output of this first step is then rendered into HTML and returned -to the user.
Note that the generic "style" template contains templating tags +to the user.
+Note that the generic "style" template contains templating tags (formwidget, formgroup, if etc.) that must be "protected" during the first step. The templating system provides the noparse -tag to do this.
templating\@arsdigita.com
+tag to do this. +
+templating\@arsdigita.com +
+ Last modified: $Id: memory.html,v 1.1.1.1 2001/03/13 22:59:27 ben Exp $ - Index: openacs-4/packages/acs-templating/www/doc/demo/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/demo/index.adp,v diff -u -N -r1.3.2.1 -r1.3.2.2 --- openacs-4/packages/acs-templating/www/doc/demo/index.adp 20 Aug 2015 17:19:53 -0000 1.3.2.1 +++ openacs-4/packages/acs-templating/www/doc/demo/index.adp 25 Aug 2015 18:02:14 -0000 1.3.2.2 @@ -2,16 +2,25 @@{/doc/acs-templating {Templating}} {Templating System Samples} Templating System Samples + Samples
+Templating System + : Demo - -Samples
Templating System : Demo - As the links reveal, the "Data" files have the extension -.tcland the "Template" files have.adp. +.tcl+ and the "Template" files have.adp+. If you want to see a little behind the scenes, you can look at the tcl code into which we compile the template. The last column will deliver the resulting page to your browser. -Mechanisms underlaid in red are known to not work.
General
+
+Mechanisms underlaid in red are known to not work.
+General
+ + + + + +
Description Data Template Compiled
TemplateOutput @@ -26,7 +35,11 @@- Comments None View View View Combining templates
+
+Combining templates
+ + +
- Description Data Template Compiled
TemplateOutput @@ -54,7 +67,13 @@ Start
Included
MasterView Embedded Tcl
+
+Embedded Tcl
+ + + + +
Description Data Template Compiled
TemplateOutput @@ -67,11 +86,19 @@- Puts (if you absolutely must) View View View View Iteration
+Iteration
+ To see the following examples with different data, you can enter additional users into the sample table with "a simple form" or change them with "editing: several pages in one" in section -Using the Form Manager below.+Using the Form Manager + below. + + + + +
+
Description Data Template Compiled
TemplateOutput @@ -90,7 +117,12 @@- Repeating template chunks for each element of a list View View View View Both Iteration and Composition
+
+Both Iteration and Composition
+ + + +
Description Data Template Compiled
TemplateOutput @@ -111,7 +143,18 @@- Processing a template from a string (not file) View View View View Using ListBuilder
+
+Using ListBuilder
+ + + + + + + + + +
- Description Data Template Compiled
TemplateOutput @@ -195,7 +238,11 @@ index
View Forms
+
+Forms
+ + +
Description Data Template Compiled
TemplateOutput @@ -210,7 +257,19 @@- Report an error related to a request. View View Plain View Using the Form Manager.
+
+Using the Form Manager.
+ + + + + + + + + + +
Description Data Template Compiled
TemplateOutput @@ -245,5 +304,7 @@- A form with multiple submit buttons View View View View
templating\@arsdigita.com - +
+
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/exercise/ats-for-designers.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/exercise/ats-for-designers.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/exercise/ats-for-designers.adp 27 Oct 2014 16:40:22 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/exercise/ats-for-designers.adp 25 Aug 2015 18:02:14 -0000 1.2.2.1 @@ -2,36 +2,47 @@{/doc/acs-templating {Templating}} {The ACS Templating System for Web Designers} The ACS Templating System for Web Designers - - - The ACS Templating System for Web Designers
Reading
+
+The ACS Templating System for Web Designers
+Reading
+
- ACS Templating System documents
- Templating System demo
- Read beginning and end of Using Templates in ACS 4
-Sections
+
Sections
+Overview
This series of exercises is meant as a learning tool for any web + +
Overview
+This series of exercises is meant as a learning tool for any web graphic designer wanting or needing to understand how the ACS Templating System, or ATS, works, and how to use it in building web -pages.
First, perhaps an explanation of what the templating system does +pages.
+First, perhaps an explanation of what the templating system does will help us understand how it works. An ATS template itself serves as a reusable, unchanging framework that delivers dynamic data. The advantage to this is something you probably already realize: you need only build and edit a few pages to maintain a consistent presentation style while accomodating numerous permutaions of -changing data.
This training module will teach largely by exercise and example, +changing data.
+This training module will teach largely by exercise and example, but you should also refer regularly to the ATS documents provided and more specific -pointers will be given to help you out along the way.
Okay, let's get to the nitty gritty.
Exercises
The basic building block of dynamic data in a template is the +pointers will be given to help you out along the way.
+Okay, let's get to the nitty gritty.
+Exercises
+The basic building block of dynamic data in a template is the onevalue variable. A variable is simply a tag used in your
.adpfile that holds data supplied by another source file; that source will probably be another file of the same name with a.tclextension. -Variable tags come in three basic formats, as lists, multiples and onevalues.+Variable tags come in three basic formats, as lists, multiples and onevalues.
+Exercise 1: Onevalues, onelists, multilists and multirows
-(nestedlists, too?)Let's first take a look at some list and variable tags in +(nestedlists, too?)
+Let's first take a look at some list and variable tags in action. Open up another browser and look at this page, which is a text rendition of the
/ats/doc/exercise/list-and-var-sample.tclpage we'll be sourcing our data from; at the top of the page you'll find @@ -46,7 +57,8 @@ the format of it's presentation. Compare what you see inlist-and-var-sample.acswith its supporting .adp file and make note of the textual and structural differences between the -two, specifically:+two, specifically: +
+
- variables in the
-.adpfile are designated with "\@" markers, like the @@ -68,16 +80,19 @@ of the multirow>.<name of a field in the multirow>\@, and can only be called within their respective<multiple>tagsYou probably noticed some other funky looking tags, too, but -ignore those for now.
Now since the variable marker
\@name\@is set in +You probably noticed some other funky looking tags, too, but +ignore those for now.
+Now since the variable marker
\@name\@is set inlist-and-var-sample.tcl, you can go ahead and edit that file to replace "(Your Name)" with whatever your name really is (be sure to leave the quotes); if you wish,edit some of the other values to personalize the page. You'll see your changes take effect upon saving the .tcl file and reloadinglist-and-var-sample.acs. In general, though, you should probably not be editing .tcl files unless you have a pretty -good sense of their innerworkings.Okay, now go back to the web browser in which you are viewing +good sense of their innerworkings.
+Okay, now go back to the web browser in which you are viewing
list-and-var-sample.acsand change the ".acs" extension to ".dat". This page displays a view of datasources generated in the .tcl file that @@ -87,16 +102,20 @@ straight from the .tcl file). Go ahead and make use of the datasource variables not already included in the .adp file; specifically, changelist-and-var-sample.adpso -that:+that: +
+
- your personal phone number information is included
- each of your friends' names serves as a hyperlink that allows the viewer to email your friend
- a listing of recently watched movies and your reactions to them follows after the information about your friends
- also, note that the use of any variable tags referring to variables not declared in the .tcl file will break the .acs page
-Congratulations! You've just created a personalized web page +
Congratulations! You've just created a personalized web page describing friends you've never met and movies you've possibly -never seen.
Exercise Two: <if> and <else>, the conditional -tags
Dynamic data implies a changing page, and also changing +never seen.
+Exercise Two: <if> and <else>, the conditional +tags
+Dynamic data implies a changing page, and also changing presentation. The <if> and <else> tags allow you to alter the format of your page to accomodate data changes. The function of <if> is @@ -105,7 +124,8 @@ closing <if> tags will be displayed if and only if \@x\@ does in fact equal 5. A complete listing of currently supported conditions and some brief explanatory notes can be found here. Also, a few more things to keep in -mind:
+mind: +
+
- in Tcl all variables, even numbers, are stored as text strings with quantitative values, so conditions like less than, greater than, and (not) between can also be used with text to determine @@ -118,7 +138,8 @@
\@a\@is greater than or equal to\@b\@and less than or equal to\@c\@; so<if \@x\@ between 4 2>will always test false- the "in" condition uses a regular expression check (or will it? come back here and revise)
-Now, alter a few of the <if> tags in +
Now, alter a few of the <if> tags in
list-and-var-samle.adpand add a few of your own. Specifically, add one <if> and <else> combination so that the friend description reads "likes chocolate" when @@ -127,21 +148,26 @@ chocolate" iflikes_chocolate_pis an empty string. Also, add one <if>, and one <if> only, so that a is appropriately changed to an for any 11-, 18- or 80- to -89-year olds.Exercise Three: The <master> and <slave> tags -- -a call to the dominatrix in you
The <master> and +89-year olds.
+Exercise Three: The <master> and <slave> tags -- +a call to the dominatrix in you
+The <master> and <slave> tags allow you to maintain a consistent style and format among pages without having to edit each page individually. To get a sense of what these tags do and how they work, go ahead and run through this short demonstration, and then use a text editor to view the related .adp files. Also, read this discussion on the use of master -pages.
One thing you may have noticed earlier about +pages.
+One thing you may have noticed earlier about
list-and-var-sample.adpis that it lacks the standard <html>, <head>, <title> and <body> tags. This is becauselist-and-var-sample.adpis, as indicated by the <master> tag at the top of the file, also a -slave section, contained withinmaster-sample.adp.Let me stress a few key points you might have already picked up +slave section, contained within
+master-sample.adp.Let me stress a few key points you might have already picked up on from the demonstration and upon examining the .adp files, and -add a few pointers:
+add a few pointers: +
+
- the <slave> tag indicates where on the master page the slave section is inserted
- slave pages indicate the source of the master file with the <master> tag, referring by the file name only, and not @@ -162,24 +188,30 @@ same name as a variable declared within the slave section's <property> tag, the master value overrides the slave's (unless the Tcl code checks for pre-existing information)
-Now that the secrets of <master> and <slave> have +
Now that the secrets of <master> and <slave> have been revealed, it's time to put a little of your newfound knowledge to use. Open up
form-sample.adp, a standalone, independently formatted html page, and enslave it to the mastery of of your personal web page. It would also be nice if you were to -label the newly inserted form with some slave-specific title.+label the newly inserted form with some slave-specific title.
+Exercise Four: The functions of <formtemplate>
-Creating forms with ATS can be as simple as inserting two tags +
+Creating forms with ATS can be as simple as inserting two tags into a page. Try this: open
form-sample.adpand add -the two following ATS tags:<formtemplate -id="add_entry"></formtemplate>Save the page and reload it. You should see now see a big +the two following ATS tags:
++<formtemplate +id="add_entry"></formtemplate>Save the page and reload it. You should see now see a big baby-blue form block; this is the ATS default style for form presentation. Aside from requiring no HTML code, the <formtemplate> default has the added convenience of automated entry validation with appropriate correction requests. Test this out by trying to submit a form without including first or last name -or gender information.
However, if ever you wish to build a form according to the +or gender information.
+However, if ever you wish to build a form according to the mandates of your own taste, <formtemplate> also leaves you this option. Manually stylizing forms with ATS requires you to learn only two more tags, <formwidget> and <formgroup>. Browse through the @@ -190,12 +222,14 @@ <input> checkboxes and radio buttons, which should be replaced with the <formgroup> tag. When working with ATS you should probably refrain from using plain <input> and -<select> tags altogether.
You may have already noticed a few <formwidget> and +<select> tags altogether.
+You may have already noticed a few <formwidget> and <formgroup> in use within the block of HTML and ATS text commented out in
form-sample.adp. Go ahead and put that block of HTML/ATS code into action by removing the comment tag wrapper and deleting the</formtemplate>tag; -you should now see a hand-built version of the same form.There are noticeable differences between the two form templates, +you should now see a hand-built version of the same form.
+There are noticeable differences between the two form templates, most obviously the lack of background color and a few missing entry fields in the manually constructed one. Maybe not so noticeable is the grouping of entry widgets into one HTML table row (check out @@ -206,15 +240,19 @@ <formgroup> is somewhat similar to the <multiple> tag in that the block of ATS code contained within the <formgroup> tags will be parsed into plain HTML once for each -<formgroup> value option.
Practice using <formwidget> and <formgroup> by +<formgroup> value option.
+Practice using <formwidget> and <formgroup> by adding the missing entry fields manually into the form. Make free use of any HTML properties to streamline the form to your liking. If you can't remember what those fields were you can replace the closing </formtemplate> tag to recover the default format, or make use of the .dat datasource page to view your developer's -description and comments about the form.
Also, try customizing your form's error response/correction +description and comments about the form.
+Also, try customizing your form's error response/correction request text. You'll need to use the <formerror> tag, an example of -which can be found under the gender formwidget.
Exercise Five: more fun with multirows
Now that you've confidently added the conditional <if> and +which can be found under the gender formwidget.
+Exercise Five: more fun with multirows
+Now that you've confidently added the conditional <if> and <else> tags to your ATS toolbelt, it's time to put those tools to good use in formatting multirow data. First, read the docs to learn about the @@ -229,7 +267,8 @@ cases should not be used within <multiple> tags. Why is this? (Take a look at how
\@address:rowcount\@is used.) Now make the following improvements to the address book listing you -found inform-sample.acs:+found in
form-sample.acs: +-
- stripe the table with banded rows of alternating grey and white, or some other color scheme of your preference
- use the
startrowattribute so that the address book listing begins at a rownumber determined by the Tcl file code @@ -241,6 +280,8 @@ pointing towards the next set of rows should not appear if the user is already viewing rows 1-5 of 5 total rows.
shuynh\@arsdigita.com -Last modified: Fri Nov 17 10:14:44 EST 2000 - + +
+shuynh\@arsdigita.com + +Last modified: Fri Nov 17 10:14:44 EST 2000 \ No newline at end of file Index: openacs-4/packages/acs-templating/www/doc/gen/proc-doc.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/gen/proc-doc.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/gen/proc-doc.adp 27 Oct 2014 16:40:22 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/gen/proc-doc.adp 25 Aug 2015 18:02:14 -0000 1.2.2.1 @@ -2,9 +2,11 @@{/doc/acs-templating {Templating}} {Commenting Tcl procedures for parsing} Commenting Tcl procedures for parsing - - - Using comments to document Tcl procedures
Templating SystemText divisions, grouping
< blah blah > The Tcl proc parser relies on three main +Using comments to document Tcl procedures
+Templating System +Text divisions, grouping
+< blah blah > + The Tcl proc parser relies on three main text markers to divvy the Tcl library file into neat compartments: namespace, procedure and directive. Each of these divisions has its own text marker(s). In the end, your Tcl file should look somthing @@ -52,12 +54,14 @@ # \@namespace ... <other namespaces>
Use of these directive markers is largely straightforward, but a more in depth guideline of how the markers guide parsing may help -those documenting their own work:
+those documenting their own work: ++the \@namespace marker
\@namespaceis used to indicate the starting @@ -145,5 +149,6 @@ If you are referring to a namespace or procedure (useprocfor the reference type), the url value is optional as long as you use the full and completely -qualified name of the namespace or procedure.
templating\@arsdigita.com - +qualified name of the namespace or procedure.
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/guide/components.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/components.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/guide/components.adp 27 Oct 2014 16:40:22 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/guide/components.adp 25 Aug 2015 18:02:14 -0000 1.2.2.1 @@ -4,25 +4,29 @@
Building Reusable Template Components
Templating System : Developer Guide : User Guide +Building Reusable Template Components
+Templating System + : Developer Guide + : User GuideMost page layouts can be separated into smaller components, many of which may appear in different contexts throughout a site. -Examples include:
-
+Examples include:
+
- A box or section of the page listing contextual links related to the contents of the page.
- A list of comments on the contents of the page.
- A search box, user poll, or other small embedded form.
- Reports and other administrative pages, where the employee may wish to assemble multiple panels of information on a single page.
- Many popular portal sites allow users to customize their home pages by choosing and arranging a set of small layout components within a table grid. -
The templating system makes it easy to build reusable components for any of the above +
The templating system makes it easy to build reusable components for any of the above scenarios. The basic process is to build a container template, which delineates the skeletal layout of the page. Component templates may then be placed in the container template with the include tag. The container may pass arguments to the -components as needed for personalization or any other purpose.
templating\@arsdigita.com - +-->
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/guide/composite.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/composite.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/guide/composite.adp 27 Oct 2014 16:40:22 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/guide/composite.adp 25 Aug 2015 18:02:14 -0000 1.2.2.1 @@ -2,25 +2,32 @@
Assembling a Page from Components
Templating System : Developer Guide : User -Guide : Composite +Assembling a Page from Components
+Templating System + : Developer Guide + : User +Guide + : CompositeA typical page served to a browser is made up from several component pages. The idea is to have reusable parts (widgets, skins), a bit like in a programming language where code that may be used more than once makes up a procedure. The complete page may -have the following structure.
+have the following structure.
+
The "root" page includes the "widget" and wraps itself in the -"master". That page in turn includes the "top" and "bottom". Overall structureThe parts are put together with the |
The "root" page includes the "widget" and wraps itself in the +"master". That page in turn includes the "top" and "bottom".
+Overall structure
+The parts are put together with the <include> tag (in the diagram
below, black links going right) and the <master> tag (brown link going
left); and the concept is similar to a procedure call. The
-structure of the composite page looks like this as a graph.
| root | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
 | ||||||||||||||||
| ||||||||||||||||
| top | bottom | |||||||||||||||
Any (sub)page can have 0 or 1 master and 0 or more included +
Any (sub)page can have 0 or 1 master and 0 or more included
pages. Each page has its own separate scope for variables.
Arguments can be passed to dependent pages as attributes to
<inlcude>, or as properties to
<master>. The directed graph of pages will often
-be be acyclic, as in the example, but this is not required.
Evaluation Order
Sometimes it is of interest in which order the different parts +be be acyclic, as in the example, but this is not required.
+Evaluation Order
+Sometimes it is of interest in which order the different parts
are evaluated. The "code" always runs first, followed by the
template. The <inlcude> tag causes the subpage
to be evaluated at this point of the template, and the rest of the
including template is evaluated after that's done. This is like a
procedure call. In contrast, the <master> tag is
deferred until the whole slave page ("root" in the example) is
-done. For our example, the following order results.
| root.tcl | |||
| master.adp | (end) | ||
Here we assume the ACS/Tcl situation, where the "code" is a tcl -script in a .tcl file. The template is a .adp file.
Variants of Page Nodes
The graph of the overall structure has five nodes, shown as a +
Here we assume the ACS/Tcl situation, where the "code" is a tcl +script in a .tcl file. The template is a .adp file.
+Variants of Page Nodes
+The graph of the overall structure has five nodes, shown as a code/template pair. This is the standard situation, where the "code" part sets up datasources and the template uses them. In some situations, the following facility can help to reduce duplication -or to handle special situations more effectively.
The "code" part can divert to another page by calling +or to handle special situations more effectively.
+The "code" part can divert to another page by calling
template::set_file to modify the file name stub of the
page being processed. For convenience,
ad_return_template can be used with the same effect;
@@ -101,7 +116,8 @@
the name is changed, the template of the original page is not used;
instead the new page is processed, code first, then template. As
that page's code can call set_file again, we get the
-following picure.
| code A |  | (template A ignored) | @@ -111,19 +127,24 @@
 | ||
| ... | ||
| ||
| code Z | template Z |
This assumes page "A" was originally wanted. An arrow () exits from code
+
This assumes page "A" was originally wanted. An arrow () exits from code
which calls template::set_file (directly or through
ad_return_template). All scripts and the template are
executed in the same scope, i.e., they share
-variables.
Furthermore either of the final files can be omitted if it is -not needed, giving three basic possibilities.
| a) | code | | template |
| b) | (no code) | template | |
| c) | code | (no template) |
It is an error to omit both parts; this is a special case -intended to speed up debugging.
templating\@arsdigita.com - +
It is an error to omit both parts; this is a special case +intended to speed up debugging.
++templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/guide/data.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/data.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/guide/data.adp 27 Oct 2014 16:40:23 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/guide/data.adp 25 Aug 2015 18:02:14 -0000 1.2.2.1 @@ -2,14 +2,18 @@
Implementing Data Sources
Templating System : Developer Guide : User Guide +Implementing Data Sources
+Templating System + : Developer Guide + : User GuideData sources are implemented in a Tcl script using regular Tcl variables, lists and arrays. The templating system includes a set of procedures to simplify the construction of data sources from -relational database queries.
The Structure of Data Sources
The templating system can manipulate four basic types of -structures as data sources:
| onevalue | A simple scalar, such as a user's first name or the total due on a purchase order. | @@ -20,48 +24,73 @@
| multirow | A multi-row, multi-column data table. |
onevalue
+
onevalue
+onevalue data sources are implemented simply by setting -a Tcl variable:
set name "Walter Cronkite"The query procedure may be used to set a onevalue data -source based on a database query:
query name onevalue "select name from users where user_id =
-123"You can embed a onevalue data source in a template with +a Tcl variable:
+set name "Walter Cronkite"
+The query procedure may be used to set a onevalue data +source based on a database query:
+query name onevalue "select name from users where user_id =
+123"
+You can embed a onevalue data source in a template with simple variable -substitution.
onerow
-onerow data sources are implemented as Tcl arrays:
set name(first_name) Walter
-set name(last_name) CronkiteThe query procedure +substitution.
+onerow
++onerow data sources are implemented as Tcl arrays:
+set name(first_name) Walter
+set name(last_name) Cronkite
+The query procedure may be used as a convenient way to store the result of a one-row -database query into an array:
+database query into an array: ++query name onerow " select first_name, last_name from users where user_id = 123" -You can embed references to column values of a onerow -data source in a template with simple variable substitution.
onelist
+
You can embed references to column values of a onerow +data source in a template with simple variable substitution.
+onelist
+onelist data sources are implemented by creating a Tcl -list:
+list: ++set names [list "Walter" "Fred" "Susy" "Frieda"] -The query procedure may be used to set a onelist data -source based on a one-column database query:
query name onevalue "select name from users"You can iterate over a onelist data source in a -template with the list tag.
multirow
+
The query procedure may be used to set a onelist data +source based on a one-column database query:
+query name onevalue "select name from users"
+You can iterate over a onelist data source in a +template with the list tag.
+multirow
+multirow data sources are not represented by a single Tcl data structure. As such the templating system includes a -special API for constructing and manipulating them.
+special API for constructing and manipulating them. ++multirow create cars make model year multirow append cars "Toyota" "Camry" "1996" multirow append cars "Volvo" "960" "1995" -The query procedure +
The query procedure may be used as a convenient way to store the result of a multi-row, multi-column database query into a multirow data -source:
+source: ++query name multirow " select make, model, year from cars" -You can iterate over a multirow data source in a +
You can iterate over a multirow data source in a template with the multiple -tag.
templating\@arsdigita.com - +tag. +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/guide/document.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/document.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/guide/document.adp 27 Oct 2014 16:40:23 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/guide/document.adp 25 Aug 2015 18:02:14 -0000 1.2.2.1 @@ -4,16 +4,19 @@
Documenting Data Sources
Templating System : Developer Guide : User Guide +Documenting Data Sources
+Templating System + : Developer Guide + : User GuideEffective coordination between the developer and designer is one of the major challenges of any publishing team. The templating system provides a set of simple documentation directives so that developer comments on data sources can be extracted from Tcl scripts and summarized for non-technical members of the publishing -team automatically.
To take advantage of this capability, the developer must -structure comments on a datasource in the following way:
+team automatically. +To take advantage of this capability, the developer must +structure comments on a datasource in the following way:
+# \@datasource cars multirow # The cars owned by a user. # \@column make The make of the car, i.e. Toyota @@ -33,7 +36,9 @@ # \@input gender radio # either "m" for male or "f" for female -A few formatting guidelines:
-
+
+
- all datasources (onevalues, onelists, multilists, multirows) are documented with the datasource directive, their name, the type of datasource, and then necessary comments:
Possible form entry types include text (or textentry), date, checkbox, radio, select, multiselect and textbox# \@datasource name <type of @@ -49,7 +54,9 @@
-
A few formatting guidelines:
+Once the templates have been enabled, the designer can simply +
Once the templates have been enabled, the designer can simply visit the URL from which the page will be served, substituting -acs with the dat extension.
templating\@arsdigita.com - +acs with the dat extension. +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/guide/form-datatypes.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/form-datatypes.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/guide/form-datatypes.adp 27 Oct 2014 16:40:23 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/guide/form-datatypes.adp 25 Aug 2015 18:02:15 -0000 1.2.2.1 @@ -2,8 +2,9 @@
Custom Data Types
Templating System : Developer Guide : User Guide -templating\@arsdigita.com - +
Custom Data Types
+Templating System + : Developer Guide + : User Guide ++templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/guide/form-process.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/form-process.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/guide/form-process.adp 27 Oct 2014 16:40:23 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/guide/form-process.adp 25 Aug 2015 18:02:15 -0000 1.2.2.1 @@ -4,17 +4,18 @@
Validating and Processing Form Submissions
+
Validating and Processing Form Submissions
+Important Note: The ad_form function has been written to be a more consistent, easier way to create and manage dynamic forms. Behind the scenes it uses the templating system's form builder, but it hides much of its complexity. You should definitely look at it and at the pages that -use it in the survey package.
The templating system provides a simple infrastructure for +use it in the survey package.
+The templating system provides a simple infrastructure for validating form submissions. The typical life-cycle of a form is as -follows:
-
+follows:
+
- The user makes the initial request for a page containing a form. The code associated with the page creates the form (with the form create command) and populates it with elements.
- The developer may use the form is_request command to @@ -29,5 +30,6 @@ same URL as that of the form itself. The submission is therefor processed within the framework of the same code that was used to create the form. -
templating\@arsdigita.com - +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/guide/form-templates.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/form-templates.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/guide/form-templates.adp 27 Oct 2014 16:40:23 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/guide/form-templates.adp 25 Aug 2015 18:02:15 -0000 1.2.2.1 @@ -4,24 +4,31 @@
Customizing Form Templates
Templating System : Developer Guide : User Guide +Customizing Form Templates
+Templating System + : Developer Guide + : User GuideThe templating system allows the designer to have full control -over the layout of a dynamic form.
Starting with an autogenerated form template
In most cases, the simplest way for the designer to get started +over the layout of a dynamic form.
+Starting with an autogenerated form template
+In most cases, the simplest way for the designer to get started is to edit the autogenerated form template. This template will have all the necessary formwidget and formgroup -tags.
Using form metadata
The designer must take care that all form elements created by +tags.
+Using form metadata
+The designer must take care that all form elements created by the developer in the code file are also represented in the associated template. Checking the template against the form metadata is the best means to ensure that elements are not -omitted.
Viewing of form metadata is not implemented yet.
templating\@arsdigita.com - +-->
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/guide/form-widgets.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/form-widgets.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/guide/form-widgets.adp 27 Oct 2014 16:40:23 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/guide/form-widgets.adp 25 Aug 2015 18:02:15 -0000 1.2.2.1 @@ -2,16 +2,18 @@
Custom Form Widgets
Templating System : Developer Guide : User Guide +Custom Form Widgets
+Templating System + : Developer Guide + : User GuideForm widgets are implemented as tcl procs that output the html to generate the form element. The tcl proc must be in the template::widget namespace. So the proc for the search widget is called template::widget::search. The code that generates the built -in widgets is in packages/acs-templating/tcl/widget-procs.tcl.
If the data from the form widget needs to be formatted or +in widgets is in packages/acs-templating/tcl/widget-procs.tcl.
+If the data from the form widget needs to be formatted or processed a tcl proc is created in the template::data::transform namespace. For example, templatete::data::transform::search. This takes the input from the user and processes it to be returned to -the tcl code handling the form.
- +the tcl code handling the form. +
Index: openacs-4/packages/acs-templating/www/doc/guide/forms.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/forms.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/guide/forms.adp 27 Oct 2014 16:40:23 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/guide/forms.adp 25 Aug 2015 18:02:15 -0000 1.2.2.1 @@ -4,30 +4,43 @@
Creating and Populating Forms
Templating System : Developer Guide : User Guide +Creating and Populating Forms
+Templating System + : Developer Guide + : User GuideThis document outlines the steps necessary to build a dynamic -form in Tcl code.
+form in Tcl code.
+Important Note: The ad_form function has been written to be a more consistent, easier way to create and manage dynamic forms. Behind the scenes it uses the templating system's form builder, but it hides much of its complexity. You should definitely look at it and at the pages that -use it in the survey package.
Create a form
Use the form create command to initialize a form:
+use it in the survey package. ++Create a form
+Use the form create command to initialize a form:
+form create add_user -See the form API for optional -parameters to this command.
Add elements
Once the form is created, use the element create -command to add elements to it:
++See the form API for optional +parameters to this command.
+Add elements
+Once the form is created, use the element create +command to add elements to it:
+element create add_user first_name -datatype text \ -label "First Name" \ -html { size 30 } -In auto-generated forms, elements appear in the order they were +
In auto-generated forms, elements appear in the order they were created. See the element API for -optional parameters to this command.
Set values
Self-validating forms should check whether a request or +optional parameters to this command.
+Set values
+Self-validating forms should check whether a request or submission is currently being processed. If a request is being processed, then form elements may need to be initialized with their -appropriate values.
+appropriate values. ++if { [template::form is_request add_user] } { set db [ns_db gethandle] @@ -39,7 +52,9 @@ template::element set_properties add_user user_id -value $user_id } -This may also be done using the value option to +
This may also be done using the value option to element create. In this case the value is set separately -to avoid the additional database query during a submission.
templating\@arsdigita.com - +to avoid the additional database query during a submission. +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/guide/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/index.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/guide/index.adp 27 Oct 2014 16:40:23 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/guide/index.adp 25 Aug 2015 18:02:15 -0000 1.2.2.1 @@ -2,12 +2,15 @@
Overview
Templating System : Developer Guide : User Guide +Overview
+Templating System + : Developer Guide + : User GuideThis document provides a brief introduction to the design of the templating system and the process of building dynamic pages with -the templating system.
Introduction
+the templating system. +Introduction
+ The templating system solves a clear business need: providing a system for efficient collaboration between designers and developers on building a web site. Writing a dynamic web page requires writing @@ -24,7 +27,8 @@ To solve this problem, the ACS Templating System, separates the responsibilities of writing the page into separate application logic and presentation layers. -How the Templating System Works
This separation is achieved through utilization of the +
How the Templating System Works
+This separation is achieved through utilization of the Model-View-Controller (MVC) pattern. The MVC pattern is a classic design pattern that identifies clear roles for components in GUI application with persistent data originally developed for @@ -36,48 +40,60 @@ the user's requests. This diagram summarizes how the process flow of the templating system using the MVC framework. The filename dynamic-page is simply -an example.
The model in the templating system is the +an example.
+The model in the templating system is the representation in the database of the ACS Objects and their associated PL/SQL package methods. The view is the ADP template that formats the datasources retrieved through the controller into a presentation for a user. The controller is the combination of the Request Processor and the application logic pages implemented as .tcl -scripts that prepare data sources for the templating system.
This framework permits a clear separation between the logic that +scripts that prepare data sources for the templating system.
+This framework permits a clear separation between the logic that retrieves data from the database and the markup that prepares the data for display. The designer can focus on presentation and usability issues and need only write HTML markup. The developer can focus on the programming necessary to retrieve the data for the designer and does not need to write HTML markup. These tasks are separated into separate files so that the two tasks do not -interfere with each other.
The design of the templating system makes it easier to include +interfere with each other.
+The design of the templating system makes it easier to include reusable presentation components as included templates and master templates, as explained in "Composite Page". Moreover, the ACS Core pages are templated which enables users of the ACS who want to customize their look and feel to update a site-wide master or the individual templates without touching the application logic. If a bug is fixed in the application logic, the application logic script can be -replaced without affecting the template.
The rest of this document explains the steps necessary to write -a templated page.
Choose the data you wish to present
The first step in building a dynamic page is to decide, at least +replaced without affecting the template.
+The rest of this document explains the steps necessary to write +a templated page.
+Choose the data you wish to present
+The first step in building a dynamic page is to decide, at least to a first approximation, on the data you wish to present to the user. For example, a site that allows users to manage their car maintenance records might want to present the following data on the -user's home page:
-
+user's home page:
+
- The user's name.
- The user's city of residence.
- A list of the user's cars, showing the year, make, and model.
- A list of messages or alerts related to the user's cars.
- A list of local events or special offers from mechanics or dealers. -
Note that our definition of data encompasses +
Note that our definition of data encompasses everything that is unique to a particular user's experience. It does not include text or other layout -features that will appear the same for all users.
Each of the items in the above list constitutes a data +features that will appear the same for all users.
+Each of the items in the above list constitutes a data source which the system merges with a template to produce the finished page. The publisher typically describes the data to -present on each page as part of the site specification.
Implement the Data Sources
Once the publishing team has described the data to present on a +present on each page as part of the site specification.
+Implement the Data Sources
+Once the publishing team has described the data to present on a page, the developer writes a Tcl script to implement the data sources. The Tcl script should be located under the page root at the URL of the finished page. For example, a dynamic page that will be located at http://yoursite.com/cars.acs requires a Tcl script located on the server at /web/yoursite/www/cars.tcl (or wherever -your pages happen to be located).
In addition to setting data sources, the Tcl script may perform +your pages happen to be located).
+In addition to setting data sources, the Tcl script may perform any other required tasks, such as checking permissions, performing database transactions or sending email. It may also redirect to another URL if necessary. The Tcl script may optionally use logic @@ -89,17 +105,23 @@ preparation script is run in the same scope, in fact accumulating datasources. By default the templating system looks for a file with the same name as the Tcl script, but for the -template with the extension .adp.
Document the Data Sources
The developer should include comments in the Tcl code +template with the extension .adp.
+Document the Data Sources
+The developer should include comments in the Tcl code documenting each data source. A templating system specifies recognizes special documentation directives that allow the comments to be extracted from the -code and accessed by the designer or publisher for reference.
Write the Template
The final step is to write a +code and accessed by the designer or publisher for reference.
+Write the Template
+The final step is to write a template specifying the layout of the page. Template files must have the adp extension. By default the system looks for the template at the same location as the associated Tcl script, -such as /web/yoursite/www/cars.adp.
The layout is mostly HTML, with a small number of additional +such as /web/yoursite/www/cars.adp.
+The layout is mostly HTML, with a small number of additional custom tags to control the presentation of dynamic data on the page. In most cases, the initial draft of the template will be written by the developer in the course of testing the Tcl script. -The designer may then enhance the layout as required.
docs\@openacs.org - +The designer may then enhance the layout as required. +
+docs\@openacs.org Index: openacs-4/packages/acs-templating/www/doc/guide/master.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/master.adp,v diff -u -N -r1.3.2.1 -r1.3.2.2 --- openacs-4/packages/acs-templating/www/doc/guide/master.adp 20 Aug 2015 17:19:53 -0000 1.3.2.1 +++ openacs-4/packages/acs-templating/www/doc/guide/master.adp 25 Aug 2015 18:02:15 -0000 1.3.2.2 @@ -2,16 +2,20 @@
Using Master Templates
Templating System : Developer Guide : User Guide +Using Master Templates
+Templating System + : Developer Guide + : User GuideMaster templates dramatically simplify the task of maintaining a consistent look and feel across all the pages of a site (or section of a site). This document gives a brief overview of how to -implement a master template.
Design a Content Frame
Most web pages are laid out with a central content area +implement a master template.
+Design a Content Frame
+Most web pages are laid out with a central content area where the actual unique content of the page is displayed. Surrounding the content area is a frame with common -elements that are consistent from page to page:
| Logo | Ad Banner | @@ -25,18 +29,23 @@|
| Footer | ||
Most sites use an HTML table to delineate the content area +
Most sites use an HTML table to delineate the content area within the frame, allowing for the inclusion of a sidebar along with a header and footer. Sites that opt for a simpler layout may -only have a header above and a footer below the content area.
The master template is typically highly dynamic. Menus, context +only have a header above and a footer below the content area.
+The master template is typically highly dynamic. Menus, context bars and other navigational controls must change depending on the section of the site the user is browsing. A "Related Links" box would have to reflect the specific contents of the page. The master template may also be personalized for registered users to include their name and access to restricted areas of the site. Special formatting preferences may also be applied for registered -users.
Write the Master Template
A master template to implement the page layout shown above would -have this basic structure:
++users. +Write the Master Template
+A master template to implement the page layout shown above would +have this basic structure:
+<html><body><table width=100% cellspacing=0 cellpadding=0 border=0> <tr> @@ -57,53 +66,68 @@ <tr><td colspan=3><!-- FOOTER --></td></tr> </table></body></html> -The only special feature of this master template is the +
The only special feature of this master template is the slave tag, which marks the location of the content area. Note that the content is inserted into the master template as a single passage of HTML or plain text. The master template should always frame the content area within a td tag when using a table to specify the overall layout of the page. Page layouts that do not rely on tables often use hr tags to demarcate the -content area from the header and footer.
Write the Page Template(s)
A page template must include a master tag to specify -that its output should be enclosed in a master template:
++content area from the header and footer. +Write the Page Template(s)
+A page template must include a master tag to specify +that its output should be enclosed in a master template:
+<master src="/templates/master"> <!--Begin layout of page content--> <h3>\@title\@</h3> <p>by \@name\@</p> <p><b>\@byline\@</b>: \@text</p> ... -The master tag may be included anywhere in the body of +
The master tag may be included anywhere in the body of the page template, although usually the top of the file is the best -location for it.
Adding Dynamic Elements to the Master Template
The master template may be associated with its own Tcl script, +location for it.
+Adding Dynamic Elements to the Master Template
+The master template may be associated with its own Tcl script, which may set data sources to support dynamic elements outside the main content area. For example, you might wish to include the user's name on every page to indicate that the site has been personalized. The Tcl script associated with the master template -would include code like this:
++would include code like this: +set user_name [your_procedure_to_get_the_current_user_name] -The template would have a section like this:
++The template would have a section like this:
+<if \@user_name\@ nil> <a href="/register.acs">Register Now!</a> </if> <else> \@user_name\@ (<a href="/signout.acs">Sign Out</a>) </else> -Passing Property Values from the Page Template to Master -Template
As mentioned above, in many cases the dynamic elements of the +
Passing Property Values from the Page Template to Master +Template
+As mentioned above, in many cases the dynamic elements of the master template depend on whatever is appearing in the content area for a particular request. The property tag may be used in the page template to specify values that should be passed to the -master template:
++master template: +<master src="/templates/master"> <property name="title">\@title\@</property> <!--Begin layout of page content--> ... -In this case, the property tag establishes +
In this case, the property tag establishes title as a data source for the master template. Properties are set as regular Tcl variables prior to executing the Tcl script associated with the master template. This allows the page template to pass an ID which the Tcl script associated with the master -template may use to query for additional information.
templating\@arsdigita.com - +template may use to query for additional information. +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/guide/search.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/search.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/guide/search.adp 27 Oct 2014 16:40:24 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/guide/search.adp 25 Aug 2015 18:02:15 -0000 1.2.2.1 @@ -4,13 +4,13 @@
Implementing Search-and-Select Forms
Form designers are often confronted by the need to provide users +
Implementing Search-and-Select Forms
+Form designers are often confronted by the need to provide users with a way to choose from hundreds or even thousands of potential options, exceeding the practical capacity of a select list or set of checkboxes or radio buttons. One common solution is to allow the -user to select from a search result:
-
+user to select from a search result:
+
The user is prompted to enter or choose some search criteria. For example, travel sites typically begin the reservation process by prompting the user to enter a city of origin and @@ -25,13 +25,16 @@ system prompts the user to choose a city before proceding. If no matches are found, the sytem prompts the user to search again.
-
To illustrate how to implement this type of page flow using the +
To illustrate how to implement this type of page flow using the templating system, we will build the framework for a simple user-management interface. Required actions for such an interface might include editing basic user properties, changing user -permissions or adding users to roles or groups.
The simplest way to implement this page flow using the +permissions or adding users to roles or groups.
+The simplest way to implement this page flow using the templating system is to create a single page that conditionally -includes two different forms:
-
+includes two different forms:
+
Say the administrator wishes to edit the name and screen name of a user. The administrator requests a page, user-edit.acs. The page looks for a query parameter named user_id to @@ -46,14 +49,18 @@ administrator to choose one. A link is also provided with no user_id so that the administrator may search again.
If the administrator chooses a user, the page detects the user_id and displays the edit form.
-
A working implementation of this example is provided in the +
A working implementation of this example is provided in the files demo/user-edit.tcl and demo/user-edit.adp. You must execute the demo data file (demo/demo.sql) for -the page to function.
Try the following scenarios:
-
+the page to function.
+
- Submit the search form without entering any search criteria.
- Submit the search form with obscure criteria that does not yield a match.(i.e. zzzzz).
- Submit the search form with criteria likely to produce multiple results (i.e. e).
- Submit the search form with criteria likely to product a single result (i.e. Sally). -
Try the following scenarios:
+templating\@arsdigita.com - +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/guide/skins.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/skins.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/guide/skins.adp 27 Oct 2014 16:40:24 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/guide/skins.adp 25 Aug 2015 18:02:15 -0000 1.2.2.1 @@ -4,9 +4,11 @@
Presenting Data in Multiple Styles and Formats
Templating System : Developer Guide : User Guide +Presenting Data in Multiple Styles and Formats
+Templating System + : Developer Guide + : User Guide(Discussion of how to do cobranding, syndication of data in XML, -etc.).
templating\@arsdigita.com - +etc.). +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/guide/tcl.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/tcl.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/guide/tcl.adp 27 Oct 2014 16:40:24 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/guide/tcl.adp 25 Aug 2015 18:02:15 -0000 1.2.2.1 @@ -4,14 +4,18 @@
Embedding Code in Templates
Templating System : Developer Guide : User Guide -There are various ways to use Tcl in ADPs like ASP or JSP.
You can use the There are various ways to use Tcl in ADPs like ASP or JSP. You can use the Generally, avoid putting escaped Tcl code in adp files, or
+demonstration page. Generally, avoid putting escaped Tcl code in adp files, or
generating HTML fragments in tcl procedures. It subverts the
separation of code and layout, one of the benefits of templating.
-Embedded Tcl makes templates non-portable to ACS/Java.<% ... %> and <%=
+Embedding Code in Templates
+Templating System
+ : Developer Guide
+ : User Guide
+<% ... %> and <%=
... %> tags just as in an ADP page handled by the
AOLserver. For examples, see the section "embedded tcl" on the
-demonstration page.
templating\@arsdigita.com
-
+Embedded Tcl makes templates non-portable to ACS/Java.
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/guide/templates.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/templates.adp,v diff -u -N -r1.3.2.1 -r1.3.2.2 --- openacs-4/packages/acs-templating/www/doc/guide/templates.adp 20 Aug 2015 17:19:53 -0000 1.3.2.1 +++ openacs-4/packages/acs-templating/www/doc/guide/templates.adp 25 Aug 2015 18:02:16 -0000 1.3.2.2 @@ -2,56 +2,78 @@
Writing Templates
Templates are the primary means for separating the work of +
Writing Templates
+Templates are the primary means for separating the work of developers and designers. A template is written by a designer and consists largely of static HTML (or other markup). The template author uses a small set of special markup tags to reference dynamic data prepared by the developer. A reasonably skilled template author should be able to implement a template without any assistance from the developer, other than assuring that the proper -dynamic data is accessible.
This document introduces the basic concepts underlying the use -of template tags in ACS 4.0.
Variable Substitution
Much like the mail merge feature of a word processor, template +dynamic data is accessible.
+This document introduces the basic concepts underlying the use +of template tags in ACS 4.0.
+Variable Substitution
+Much like the mail merge feature of a word processor, template authors must use special tags to position each piece of dynamic data within the layout. Each template is associated with a data -dictionary that lists all available variables.
Use of Components
To speed development and ensure consistency of design, template +dictionary that lists all available variables.
+ +Use of Components
+To speed development and ensure consistency of design, template authors are encouraged to assemble pages from distinct component templates that may be recycled in different contexts. One typical practice is to build a "master" template for an entire section of a site, with a common header, footer and sidebar layout. For each page request, the "content" template is incorporated dynamically into a specified area of the master template, usually a table -cell.
(graphic)
Another common practice is to build small reusable templates +cell.
+(graphic)
+Another common practice is to build small reusable templates that may be included in other templates as logical components. This may be useful for common "widgets" such as search boxes or lists of related links, as well as for building configurable portal pages where users may assemble different types of content to their -liking.
(graphic)
See include.
Property Declarations
Template authors need a simple mechanism for declaring +liking.
+(graphic)
+See include.
+Property Declarations
+Template authors need a simple mechanism for declaring properties within the templates. The most common use of such properties is for configuring elements of an enclosing master template, such as the title, navigation links, and whether to include a search box. The data dictionary specifies available -properties as well as the set of valid values when appropriate.
(graphic)
See property.
Conditional Insertion
Designers often need to tailor the layout depending on the +properties as well as the set of valid values when appropriate.
+(graphic)
+See property.
+Conditional Insertion
+Designers often need to tailor the layout depending on the specific data being presented. For example, when presenting a list of library books that a user has checked out, the designer might -want to highlight the overdue ones in red.
See if..else.
Iteration
Dynamic pages often present lists of values or records, each of +want to highlight the overdue ones in red.
+See if..else.
+Iteration
+Dynamic pages often present lists of values or records, each of which typically represents the results of a database query. Template authors must have a way to iterate over each value or record in such a list and format it appropriately. In the simplest scenario, the exact HTML is repeated with each iteration. However, template authors often need to vary the design depending on the -context. For example:
-
+context. For example:
+
First and last items may be formatted differently from items in between.
Special breaks may be required when a particular value changes. For example, a query may return the name and office of all employees in a company, and the designer may wish to insert a subheading for each office.
Colors or patterns may alternate between items. For example, the designer may want to have alternate between white and gray bands in a table.
-
To accomodate these type of scenarios, the template parser sets +
To accomodate these type of scenarios, the template parser sets some additional variables that the designer can reference to vary -the layout from item to item.
templating\@arsdigita.com - +the layout from item to item. + +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/guide/wizard-procs-doc.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/wizard-procs-doc.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/guide/wizard-procs-doc.adp 27 Oct 2014 16:40:24 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/guide/wizard-procs-doc.adp 25 Aug 2015 18:02:16 -0000 1.2.2.1 @@ -2,9 +2,8 @@
Overview Of How To Make A Wizard
-
+
- Create a wizard file (ex. wizard.tcl) that contains the
"template::wizard create" code.
@@ -62,7 +61,9 @@ step, like wise next buttons are not displayed if its the last step. Finish can appear on any step and will finish the current wizard even if not all steps are done.
-
Overview Of How To Make A Wizard
+Tips And How To Use The Wizard
-
+
Tips And How To Use The Wizard
+-
How do you display the steps in the wizard to serve as an indicator?
@@ -172,4 +173,3 @@ have the param again called "name" but used for the file name.
Integrating Forms into a Wizard
This document outlines the steps necessary to build a dynamic -form wizard in Tcl code.
Updated documentation of -wizardsCreate a wizard
Use the wizard create command to initialize a wizard, +
Integrating Forms into a Wizard
+This document outlines the steps necessary to build a dynamic +form wizard in Tcl code.
+Updated documentation of +wizards +Create a wizard
+Use the wizard create command to initialize a wizard, declaring any wizard state variables in the -params -option:
+option: ++wizard create make_sandwich -params { sandwich_id } -See the wizard -API for optional parameters to this command.
Add steps
Once the wizard is created, use the wizard create -command to add steps to it:
++See the wizard +API for optional parameters to this command.
+Add steps
+Once the wizard is created, use the wizard create +command to add steps to it:
+wizard add make_sandwich -label "Add the lettuce" -url "add-lettuce" -In auto-generated wizards, the wizard steps appear in the order +
In auto-generated wizards, the wizard steps appear in the order they were created. See the wizard API for optional parameters to this command. Alternatively, wizard steps can be created in the wizard create statement -with the -steps option:
+with the -steps option: ++wizard create make_sandwich -action "eat-sandwich.acs?sandwich_id=$sandwich_id" -params { sandwich_id } -steps { 1 -label "Add Meat" -url "add-meat" -repeat 2 -label "Add Lettuce" -url "add-lettuce" 3 -label "Add Cheese" -url "add-cheese" -repeat } -Setting wizard state variables
Most likely, a wizard will store one or more state variables +
Setting wizard state variables
+Most likely, a wizard will store one or more state variables using the -params option in the wizard create statement. At any point in the wizard process, a state variable's value can be updated using the wizard set_param -command.
+command. ++# check to see if a sandwich_id has been passed in by the wizard request set_param sandwich_id -datatype integer -optional @@ -45,7 +57,9 @@ wizard set_param sandwich_id $sandwich_id } -Integrating forms into the wizard
+
Integrating forms into the wizard
+ Integrating forms into the wizard involves augmenting the standard ATS form by:-
@@ -74,5 +88,6 @@
}
-
templating\@arsdigita.com - + +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/tagref/formerror.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/formerror.adp,v diff -u -N -r1.3.2.1 -r1.3.2.2 --- openacs-4/packages/acs-templating/www/doc/tagref/formerror.adp 20 Aug 2015 17:19:53 -0000 1.3.2.1 +++ openacs-4/packages/acs-templating/www/doc/tagref/formerror.adp 25 Aug 2015 18:02:16 -0000 1.3.2.2 @@ -2,11 +2,16 @@
formerror
Templating System : Designer Guide : Tag Reference : formerror -Summary
The formerror tag is used to specify the presentation -of a form validation error.
Usage
++formerror
+Templating System + : Designer Guide + : Tag Reference + : formerror +Summary
+The formerror tag is used to specify the presentation +of a form validation error.
+Usage
+<formtemplate id="add_user"> <table> <tr> @@ -22,7 +27,9 @@ </table><br> <input type=submit value="Submit"> </formtemplate> -Another example:
++Another example:
+<formtemplate id="add_user"> <table> <tr> @@ -39,9 +46,12 @@ </table><br> <input type=submit value="Submit"> </formtemplate> -This adds another table row which contains the error message for +
This adds another table row which contains the error message for that widget in red color. If there is no error then the table row -will not be added.
Notes
-
+will not be added.
+
The contents of the formerror tag may appear on the form when a submission is returned to the user for correction.
The contents of the tag may use the special variables label and value to refer to the element label and @@ -60,5 +70,6 @@ inserted (separated by <,br> tags).
See the formwidget and formgroup tags for more information on writing the body of a dynamic form template.
-
Notes
+templating\@arsdigita.com - +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/tagref/formgroup.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/formgroup.adp,v diff -u -N -r1.3.2.1 -r1.3.2.2 --- openacs-4/packages/acs-templating/www/doc/tagref/formgroup.adp 20 Aug 2015 17:19:53 -0000 1.3.2.1 +++ openacs-4/packages/acs-templating/www/doc/tagref/formgroup.adp 25 Aug 2015 18:02:16 -0000 1.3.2.2 @@ -2,14 +2,19 @@
Formgroup
Templating System : Designer Guide : Tag Reference : Formgroup -Summary
The formgroup tag is used to lay out a set of check +
Formgroup
+Templating System + : Designer Guide + : Tag Reference + : Formgroup +Summary
+The formgroup tag is used to lay out a set of check boxes or radio buttons in a dynamic form template. All the check boxes or radio buttons in a group share the same name. A button group must be created as an element in the Tcl script associated -with the template.
Usage
+with the template. +Usage
+<formtemplate id="choose_services"> <table> <formgroup id=services> @@ -18,7 +23,9 @@ </table><br> <input type=submit value="Submit"> </formtemplate> -Notes
-
+
+
The formgroup tag contains a template for formatting each check box or radio button in the group. The tag makes a special multirow data source named formgroup available in @@ -39,5 +46,6 @@
See the formtemplate and formwidget tags for more information on writing the body of a dynamic form template.
-
Notes
+templating\@arsdigita.com - +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/tagref/formtemplate.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/formtemplate.adp,v diff -u -N -r1.3.2.1 -r1.3.2.2 --- openacs-4/packages/acs-templating/www/doc/tagref/formtemplate.adp 20 Aug 2015 17:19:54 -0000 1.3.2.1 +++ openacs-4/packages/acs-templating/www/doc/tagref/formtemplate.adp 25 Aug 2015 18:02:16 -0000 1.3.2.2 @@ -2,12 +2,17 @@
Formtemplate
Templating System : Designer Guide : Tag Reference : Formtemplate -Summary
The formtemplate tag is used to embed a dynamic form in +
Formtemplate
+Templating System + : Designer Guide + : Tag Reference + : Formtemplate +Summary
+The formtemplate tag is used to embed a dynamic form in a template. The elements of the form must be created in the Tcl -script associated with the template.
Usage
+script associated with the template. +Usage
+<formtemplate id="add_user"> <table> <tr> @@ -19,7 +24,9 @@ </table><br> <input type=submit value="Submit"> </formtemplate> -Notes
-
+
+
The formtemplate tag takes the place of the form tag in a static HTML form. Explicit form tags in the template should not be used to enclose dynamic forms.
- @@ -45,5 +52,6 @@
See the formwidget and formgroup tags for more information on writing the body of a dynamic form template.
-
Notes
+templating\@arsdigita.com - +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/tagref/formwidget.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/formwidget.adp,v diff -u -N -r1.3.2.1 -r1.3.2.2 --- openacs-4/packages/acs-templating/www/doc/tagref/formwidget.adp 20 Aug 2015 17:19:54 -0000 1.3.2.1 +++ openacs-4/packages/acs-templating/www/doc/tagref/formwidget.adp 25 Aug 2015 18:02:16 -0000 1.3.2.2 @@ -2,12 +2,17 @@
Formwidget
Templating System : Designer Guide : Tag Reference : Formwidget -Summary
The formwidget tag is used to position a form element +
Formwidget
+Templating System + : Designer Guide + : Tag Reference + : Formwidget +Summary
+The formwidget tag is used to position a form element in a dynamic form template. The element itself must be created in -the Tcl script associated with the template.
Usage
+the Tcl script associated with the template. +Usage
+<formtemplate id="add_user"> <table> <tr> @@ -19,7 +24,9 @@ </table><br> <input type=submit value="Submit"> </formtemplate> -Notes
-
+
+
The formwidget tag takes the place of input and select tags in static HTML forms. The system substitutes these tags with the appropriate HTML tags, complete @@ -36,5 +43,6 @@
See the formtemplate and formgroup tags for more information on writing the body of a dynamic form template.
-
Notes
+templating\@arsdigita.com - +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/tagref/grid.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/grid.adp,v diff -u -N -r1.3.2.1 -r1.3.2.2 --- openacs-4/packages/acs-templating/www/doc/tagref/grid.adp 20 Aug 2015 17:19:54 -0000 1.3.2.1 +++ openacs-4/packages/acs-templating/www/doc/tagref/grid.adp 25 Aug 2015 18:02:16 -0000 1.3.2.2 @@ -2,11 +2,16 @@
Grid
Templating System : Designer Guide : Tag Reference : Grid -Summary
The grid tag is used to output each row of a multirow -datasource as a cell of an n column grid.
Usage
+Grid
+Templating System + : Designer Guide + : Tag Reference + : Grid +Summary
+The grid tag is used to output each row of a multirow +datasource as a cell of an n column grid.
+Usage
+<!-- Begid grid layout, i.e. <table> --> <table> @@ -40,7 +45,9 @@ </if> </grid> -Notes
-
+
+
-
Rows from the data source are output in column-first order. For example, if a datsource has 10 datasources and the grid has 3 @@ -69,5 +76,6 @@
Note that this is different from the multiple tag, where the \@datasource.rownum\@ is used for this effect.
-
Notes
+templating\@arsdigita.com - +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/tagref/group.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/group.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/tagref/group.adp 27 Oct 2014 16:40:25 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/tagref/group.adp 25 Aug 2015 18:02:16 -0000 1.2.2.1 @@ -2,16 +2,21 @@
Group
Templating System : Designer Guide : Tag Reference : Group -Summary
The group tag is used only within the body of a +
Group
+Templating System + : Designer Guide + : Tag Reference + : Group +Summary
+The group tag is used only within the body of a multiple tag to provide additional formatting control between subsets of a multirow data source. The tag takes a column name from the enclosing multiple tag as its only attribute. It repeats a template section as long as the value of -the column does not change from row to row.
The group tag also sets two additional values in your -multirow:
-
+the column does not change from row to row.
+
- groupnum is the rownum within the innermost group tag, starting from 1, 2, 3, etc.
- @@ -21,7 +26,9 @@ only works inside the inner-mostgroup if you have multiple group tags nested within each other. -
The group tag also sets two additional values in your +multirow:
+Usage
+ ++Usage
+<table> <multiple name="shirts"> @@ -54,15 +61,21 @@ </multiple> </table> -[Note: Carsten added this feature during the Berlin Hackaton -2004-02-14]
The delimiter attribute will add a string after each -row except the last row in the group:
++[Note: Carsten added this feature during the Berlin Hackaton +2004-02-14]
+The delimiter attribute will add a string after each +row except the last row in the group:
+<group delimiter=" | "> ... -This attribute will cause the rows within the group to appear to +
This attribute will cause the rows within the group to appear to be sepparated by vertical bars. This is much more convenient than using the <groupnum_last_p> tags to check whether we -are on the last row.
Notes
-
+are on the last row.
+
Group tags may be nested to perform even more complex formatting.
Be careful when nesting several group tags. The group tag works @@ -74,5 +87,6 @@ derived column, which contains e.g. "$f1,$f2", and use that as the column for the inner group tag. (See also this bug).
-
Notes
+templating\@arsdigita.com - +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/tagref/if.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/if.adp,v diff -u -N -r1.3.2.1 -r1.3.2.2 --- openacs-4/packages/acs-templating/www/doc/tagref/if.adp 20 Aug 2015 17:19:54 -0000 1.3.2.1 +++ openacs-4/packages/acs-templating/www/doc/tagref/if.adp 25 Aug 2015 18:02:16 -0000 1.3.2.2 @@ -2,11 +2,16 @@
If
Templating System : Designer Guide : Tag Reference : If -Summary
The if tag is used to output a template section only -when certain conditions are met.
Usage Examples
++If
+Templating System + : Designer Guide + : Tag Reference + : If +Summary
+The if tag is used to output a template section only +when certain conditions are met.
+Usage Examples
+<if \@x\@ eq 5>True</if> <if \@x\@ eq "Greta">True</if> @@ -33,16 +38,25 @@ <if \@z\@ in "Greta" "Fred" "Sam">True</if> <if \@z\@ not in "Greta" "Fred" "Sam">True</if> -Expression Syntax
+
Expression Syntax
+ The condition of the <if> tag is built from terms of the formx0 [-The operatornot]opx1x2 ...
op determines the number operands
-(x0, ...
-x
-n-1).
-The following operators are available:
-
+
+The operator
- binary
- @@ -91,8 +105,11 @@
- Any legal variables that may be referenced in the template may also be used in if statements. Words not surrounded with the commerical at sign (\@) are interpreted literally.
- @@ -132,5 +149,6 @@ way to group statements to change the order of evaluation.
When a variable is tested using the nil operator, it will return true if the variable is undefined or if the value of the variable is an empty string.
-
op
+ determines the number operands
+(x
+0
+, ...
+x
+
+n-1
+).
+The following operators are available:
+Any of these operators can be prefixed with
-not to invert the outcome.
Notes
-
+
Any of these operators can be prefixed with
+not to invert the outcome.
Notes
+templating\@arsdigita.com - +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/tagref/include-optional.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/include-optional.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/tagref/include-optional.adp 27 Oct 2014 16:40:25 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/tagref/include-optional.adp 25 Aug 2015 18:02:16 -0000 1.2.2.1 @@ -2,15 +2,21 @@
Include
Templating System : Designer Guide : Tag Reference : include-optional -Summary
The include-optional tag is used to include another +
Include
+Templating System + : Designer Guide + : Tag Reference + : include-optional +Summary
+The include-optional tag is used to include another template in the current template, but make some other chunk dependent on whether or not the included template returned -something.
This is useful if, say, you want to wrap the template with some +something.
+This is useful if, say, you want to wrap the template with some HTML, for example, a frame in a portal, but if there's nothing to -show, you don't want to show the frame either.
Usage
+show, you don't want to show the frame either. +Usage
+<include-optional src="blog-months"> <tr> <th bgcolor="\@header_background_color\@"> @@ -28,8 +34,11 @@ </td> </tr> </include-optional> -Notes
- The output of the included template will be put where the -<include-output> appears.
Tag added by: Lars Pinds (lars\@collaboraid.net)
+ +
Notes
+- The output of the included template will be put where the +<include-output> appears.
+Tag added by: Lars Pinds (lars\@collaboraid.net)
Documentation added from sources on Nov 2002, Roberto Mello. - Index: openacs-4/packages/acs-templating/www/doc/tagref/include.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/include.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/tagref/include.adp 27 Oct 2014 16:40:25 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/tagref/include.adp 25 Aug 2015 18:02:17 -0000 1.2.2.1 @@ -2,19 +2,27 @@
Include
Templating System : Designer Guide : Tag Reference : Include -Summary
The include tag is used to include a dynamic +
Include
+Templating System + : Designer Guide + : Tag Reference + : Include +Summary
+The include tag is used to include a dynamic subtemplate into the current template. Subtemplates are evaluated in the same fashion as any other dynamic template; the developer -may associate data sources and other properties to them.
Usage
+may associate data sources and other properties to them. +Usage
+<include src="subtemplate" attribute="value" ...>+ or<include src="/packages/packagename/www/lib/subtemplate" attribute="value" ...> -Notes
-
+
+
- Arguments may be passed to the subtemplate by specifying
additional attributes to the include tag. All attributes
except for src are assumed to be arguments and are set as
@@ -25,13 +33,14 @@
<include src="subtemplate" source_id="\@source_id\@" ...>
Note that passing an html string to a subtemplate via
-
\@var\@will result in passing an html-escaped string. -To prevent this, use\@var;noquote\@when passing html -to subtemplates. Alternatively the variable can by passed by name -(similar to call-by-reference) causing a variable alias to be -created in the scope of the subtemplate. This variant is necessary -for e.g. passing a Tcl array like a templating datasource. To pass -e.g.usersby reference, use this notation: +\@var\@will result in passing an html-escaped and +internationalized string. To prevent this, use +\@var;literal\@when passing html to subtemplates. +Alternatively the variable can by passed by name (similar to +call-by-reference) causing a variable alias to be created in the +scope of the subtemplate. This variant is necessary for e.g. +passing a Tcl array like a templating datasource. To pass e.g. +usersby reference, use this notation:<include src="subtemplate" &persons="users" ...>
@@ -58,5 +67,5 @@ surrounding the subtemplate, then care must be taken that the subtemplate does not contain any blank lines at the beginning or end of the file.
-
Notes
+- +
Index: openacs-4/packages/acs-templating/www/doc/tagref/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/index.adp,v diff -u -N -r1.2.2.6 -r1.2.2.7 --- openacs-4/packages/acs-templating/www/doc/tagref/index.adp 21 Aug 2015 10:49:22 -0000 1.2.2.6 +++ openacs-4/packages/acs-templating/www/doc/tagref/index.adp 25 Aug 2015 18:02:17 -0000 1.2.2.7 @@ -2,23 +2,30 @@
Template Markup Tag Reference
Templating System : Designer Guide : Tag Reference -Overview
The publishing system implements a small number of special +
Template Markup Tag Reference
+Templating System + : Designer Guide + : Tag Reference +Overview
+The publishing system implements a small number of special markup tags that allow template authors to add dynamic features to their work. The tags allow authors to accomplish four basic tasks -that are not possible with standard HTML:
-
+that are not possible with standard HTML:
+
- Embed a dynamic variable in a template (variables).
- Repeat a template section for each object in a dynamic list of objects (multiple, grid).
- Output different template sections depending on the value of one or more dynamic variables (if).
- Provide a mechanism for building complete pages from multiple component templates (include). -
- Variables
<multiple><group><grid><list><if>,<elseif>,<else><switch>,<case>,<default><include><include-optional><property><noparse><master><slave><formtemplate><formwidget><formgroup><formerror>
-Template tags are processed by the server each time a page is requested. The end result of this processing is a standard HTML page that is delivered to the user. Users do not see template tags @@ -40,7 +47,9 @@ reduces the legibility of the template to others who need to edit the template later.
-
Available Tags
-
+
Available Tags
+Notes
-
+
Notes
++Christian +Brechbühler + Last modified: $Id$ - Index: openacs-4/packages/acs-templating/www/doc/tagref/list.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/list.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/tagref/list.adp 27 Oct 2014 16:40:25 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/tagref/list.adp 25 Aug 2015 18:02:17 -0000 1.2.2.1 @@ -2,11 +2,16 @@
List
Templating System : Designer Guide : Tag Reference : List -Summary
The list tag is used to repeat a template section for -each item in a list data source.
Usage
+List
+Templating System + : Designer Guide + : Tag Reference + : List +Summary
+The list tag is used to repeat a template section for +each item in a list data source.
+Usage
+<list name="datasource"> <if \@datasource:rownum\@ ne \@datasource:rowcount\@> @@ -17,12 +22,15 @@ </else> </list> -Notes
-
+
+
The special variable datasource:rownum has the same meaning as the special column datasource.rownum in the body of a multiple tag.
The special variable datasource:rowcount has the same meaning in the list context as it does for multirow data sources.
-
Notes
+templating\@arsdigita.com - +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/tagref/master.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/master.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/tagref/master.adp 27 Oct 2014 16:40:25 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/tagref/master.adp 25 Aug 2015 18:02:17 -0000 1.2.2.1 @@ -2,22 +2,30 @@
Master
Templating System : Designer Guide : Tag Reference : Master -Summary
The master tag is used to specify the relative or +
Master
+Templating System + : Designer Guide + : Tag Reference + : Master +Summary
+The master tag is used to specify the relative or absolute URL of another template to serve as a frame for the current template. The entire contents of the current template are inserted into the master template at a position designated by the slave tag in the master -template.
Usage
+template. +Usage
+<master src="master"> <property name="title">My Home Page</property> <p>Welcome to my home page!</p> ... -Note(s)
templating\@arsdigita.com - + +
Note(s)
+ ++templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/tagref/multiple.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/multiple.adp,v diff -u -N -r1.3.2.1 -r1.3.2.2 --- openacs-4/packages/acs-templating/www/doc/tagref/multiple.adp 20 Aug 2015 17:19:54 -0000 1.3.2.1 +++ openacs-4/packages/acs-templating/www/doc/tagref/multiple.adp 25 Aug 2015 18:02:17 -0000 1.3.2.2 @@ -2,13 +2,18 @@
Multiple
Templating System : Designer Guide : Tag Reference : Multiple -Summary
The multiple tag is used to repeat a template section +
Multiple
+Templating System + : Designer Guide + : Tag Reference + : Multiple +Summary
+The multiple tag is used to repeat a template section for each row of a multirow data source. Column variables are reset with each repetition to the values of the next row of the data -source.
Usage
+source. +Usage
+<!-- Begin multiple layout, i.e. <table> --> <table> @@ -35,7 +40,10 @@ <!-- End multiple layout, i.e. </table> --> </table> -Notes
-
+
+
Notes
+The special variable datasource:rowcount may be used to check for no rows in a data source (or any other special condition related to the number of rows in the data source).
-
@@ -83,5 +91,6 @@
formatting subsets of a multirow data source. In the current
implementation, the
<multiple>tag does not nest.
-
templating\@arsdigita.com - + +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/tagref/noparse.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/noparse.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/tagref/noparse.adp 27 Oct 2014 16:40:26 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/tagref/noparse.adp 25 Aug 2015 18:02:17 -0000 1.2.2.1 @@ -2,22 +2,27 @@
Noparse
Summary
The noparse tag is used to protect template tags that +
Noparse
+Summary
+The noparse tag is used to protect template tags that should not be parsed. It is useful when templates are generated dynamically. For example, the templating system uses the noparse tag in the "style" templates used for -auto-generated forms.
Usage
+auto-generated forms. +Usage
+<noparse> <multiple name=cars> \\@cars.make\\@ \\@cars.model\\@ </multiple> </noparse> -Note(s)
Normal variable references are interpreted, even within + +
Note(s)
+Normal variable references are interpreted, even within a noparse tag. This is useful for generating templates where the attributes of the output template (such as references to component templates in an include tag or to form elements -in a formwidget tag) must be
templating\@arsdigita.com - +in a formwidget tag) must be
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/tagref/property.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/property.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/tagref/property.adp 27 Oct 2014 16:40:26 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/tagref/property.adp 25 Aug 2015 18:02:17 -0000 1.2.2.1 @@ -2,21 +2,29 @@
Property
Templating System : Designer Guide : Tag Reference : Property -Summary
The property tag is used to set display attributes of +
Property
+Templating System + : Designer Guide + : Tag Reference + : Property +Summary
+The property tag is used to set display attributes of the page. The contents of the tag may be plain text, static HTML, or a dynamic template that references local data sources. Properties are most commonly used to pass information to a master -template, such as a title or logo.
Usage
+template, such as a title or logo. +Usage
+<master src="master"> <property name="title">My Home Page</property> <p>Welcome to my home page!</p> ... -Note(s)
templating\@arsdigita.com - + +
Note(s)
+ ++templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/tagref/slave.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/slave.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/tagref/slave.adp 27 Oct 2014 16:40:26 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/tagref/slave.adp 25 Aug 2015 18:02:17 -0000 1.2.2.1 @@ -2,11 +2,16 @@
Slave
Templating System : Designer Guide : Tag Reference : Slave -Summary
The slave tag is used to mark the position in the -master template where the body template should be inserted.
Usage
+Slave
+Templating System + : Designer Guide + : Tag Reference + : Slave +Summary
+The slave tag is used to mark the position in the +master template where the body template should be inserted.
+Usage
+<html> <head><title>\@title\@</title></head> <body> @@ -16,6 +21,9 @@ <slave> </blockquote> <hr> -Note(s)
templating\@arsdigita.com - + +
Note(s)
+ ++templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/tagref/switch.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/switch.adp,v diff -u -N -r1.3.2.1 -r1.3.2.2 --- openacs-4/packages/acs-templating/www/doc/tagref/switch.adp 20 Aug 2015 17:19:54 -0000 1.3.2.1 +++ openacs-4/packages/acs-templating/www/doc/tagref/switch.adp 25 Aug 2015 18:02:17 -0000 1.3.2.2 @@ -2,13 +2,18 @@
Switch
Templating System : Designer Guide : Tag Reference : Switch -Summary
The switch tag is used to output one of n-sections when +
Switch
+Templating System + : Designer Guide + : Tag Reference + : Switch +Summary
+The switch tag is used to output one of n-sections when the switch variable matches one of the n-case statements. A default section can also be output if none of the n-case statements matches -the switch variable.
Usage Examples
+the switch variable. +Usage Examples
+<switch \@x\@> <case value="Fred"> Hello Fred. @@ -23,8 +28,10 @@ I don't recognize your name. </default> </switch> -Tcl-equivalent flags have the same meaning as in the tcl-switch -statement. Supported flags include exact, glob, and regexp.
++Tcl-equivalent flags have the same meaning as in the tcl-switch +statement. Supported flags include exact, glob, and regexp.
+<switch flag=glob \@x\@> <case value="F*"> Hello Fred. @@ -39,8 +46,10 @@ You are in the section for people whose names start with F, G, or H. </default> </switch> -Case tags also have an alternative form for matching a list of -items.
++Case tags also have an alternative form for matching a list of +items.
+<switch \@x\@> <case in "Fred" "Greta" "Sam"> Your must be Fred Greta or Sam, but I'm not sure which one. @@ -49,7 +58,9 @@ I don't recognize your name. </default> </switch> -Notes
-
+
+
Any legal variables that may be referenced in the template may also be used in switch statements.
-
Phrases with spaces in them must be enclosed in double quotes @@ -60,5 +71,6 @@ </case>
-
Notes
+templating\@arsdigita.com - +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/tagref/variable.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/variable.adp,v diff -u -N -r1.3.2.1 -r1.3.2.2 --- openacs-4/packages/acs-templating/www/doc/tagref/variable.adp 20 Aug 2015 17:19:54 -0000 1.3.2.1 +++ openacs-4/packages/acs-templating/www/doc/tagref/variable.adp 25 Aug 2015 18:02:17 -0000 1.3.2.2 @@ -2,22 +2,35 @@
Variables
Templating System : Designer Guide : Tag Reference : Variables -Summary
Variables are used in templates as placeholders for dynamic -data.
Usage
Simple variables are referenced by surrounding the variable name -with "commercial at" (\@) signs:
++Variables
+Templating System + : Designer Guide + : Tag Reference + : Variables +Summary
+Variables are used in templates as placeholders for dynamic +data.
+Usage
+Simple variables are referenced by surrounding the variable name +with "commercial at" (\@) signs:
+<!-- simple variables --> <b><i>\@first_name\@ \@last_name\@</b></i> -When processing this template, the server will look for +
When processing this template, the server will look for variables named first_name and last_name and -substitute their values in the output:
+substitute their values in the output: +<b><i>Fred Finkel</b></i> -The columns of a row variable are referenced by separating the -data source name and column with a period:
++The columns of a row variable are referenced by separating the +data source name and column with a period:
+<!-- onerow or multirow data sources --> <b><i>\@user.first_name\@ \@user.last_name\@</b></i> -Note(s)
An attempt to reference a variable that does not exist will -cause an error message to appear in the browser.
templating\@arsdigita.com - + +
Note(s)
+An attempt to reference a variable that does not exist will +cause an error message to appear in the browser.
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/widgets/date.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/widgets/date.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/widgets/date.adp 27 Oct 2014 16:40:26 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/widgets/date.adp 25 Aug 2015 18:02:17 -0000 1.2.2.1 @@ -2,42 +2,51 @@
The Date Widget
Overview
The date widget provides a versatile HTML control for entering +
The Date Widget
+Overview
+The date widget provides a versatile HTML control for entering
dates in a variety of formats. The widget operates in conjunction
with various template::util::date functions in order
to validate and manipulate the user's input. Please see the
demo pages for some examples of
-the widget's behavior.
The Date Object
The widget's value is a Date object, defined in +the widget's behavior.
+The Date Object
+The widget's value is a Date object, defined in
template::util::date. The date object stores 7 fields:
the year, month, day, hours, minutes, seconds, and the format in
which these values should be displayed. The function
template::util::date::create can be used to
-instantiate a blank date:
++instantiate a blank date: +proc template::util::date::create { {year {}} {month {}} {day {}} {hours {}} {minutes {}} {seconds {}} {format "YYYY/MM/DD"} } { return [list $year $month $day $hours $minutes $seconds $format] } -The two functions +
The two functions
template::util::date::get_property and
template::util::date::set_property are used to get or
set the fields of a Date object. The get_property
function accepts the desired field and the Date object, and returns
-the value of the field:
++the value of the field: +proc template::util::date::get_property { what date } { ... } -The
set_propertyfunction accepts the field, the +
The set_property function accepts the field, the
Date object and the new value, and returns the modified Date
-object:
++object: +proc template::util::date::set_property { what date value } { ... } -The fields which can be accessed or changed are summarized -below:
+ +
+The fields which can be accessed or changed are summarized +below:
+
Field Get ? Set ? Meaning Sample Value @@ -90,8 +99,10 @@ is currently the only way to perform arithmetic operations on dates, such as adding a day, comparing two dates, etc. -(An integer representing the number of elapsed seconds) For example, the following code produces the tomorrow's date in -SQL:
+For example, the following code produces the tomorrow's date in +SQL:
+# Create a blank date set today_date [template::util::date::create] @@ -105,11 +116,14 @@ set tomorrow_sql [template::util::date::get_property \ sql_date $tomorrow_date] -The Date Element
The widget is created with the usual
template::element +
The Date Element
+The widget is created with the usual template::element
create statement, with the datatype and widget set to
date. In addition, the element requires a
-format switch, which specifies the format for the
-date, as follows:
| Option | Format | Meaning |
|---|---|---|
| Custom format | See below |
Any other value for the format flag is interpreted
+
Any other value for the format flag is interpreted
as a custom format string. The custom format string should consist
of format specifiers separated by any of /\-.: or
-spaces. The valid format specifiers are as follows:
| Format Specifier | Field | Default Widget | |
|---|---|---|---|
AM | ampm | Selection list of "A.M." and "P.M." |
Any format specifier may be followed by a lowercase +
Any format specifier may be followed by a lowercase
t, in order to force the widget to use an input box
(instead of a selection list) for entering the specified date
-fragment.
The -format switch is required, but the date widget
-also supports the following optional switches:
| Switch | Meaning | Example |
|---|---|---|
-help |
Examples of various Date widgets can be found on the demo pages.
templating\@arsdigita.com - +
Examples of various Date widgets can be found on the demo pages.
++templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/widgets/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/widgets/index.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/widgets/index.adp 27 Oct 2014 16:40:26 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/widgets/index.adp 25 Aug 2015 18:02:17 -0000 1.2.2.1 @@ -2,10 +2,10 @@
Slave
-
+
- Input widgets
- Select widgets
- Date widget
- Search widgets
- Table widget (preliminary) -
Slave
+templating\@arsdigita.com - +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/widgets/input.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/widgets/input.adp,v diff -u -N -r1.4.2.1 -r1.4.2.2 --- openacs-4/packages/acs-templating/www/doc/widgets/input.adp 20 Aug 2015 17:19:54 -0000 1.4.2.1 +++ openacs-4/packages/acs-templating/www/doc/widgets/input.adp 25 Aug 2015 18:02:17 -0000 1.4.2.2 @@ -2,43 +2,56 @@
The Input Widgets
Overview
These widgets provide a variety of HTML controls, all of which +
The Input Widgets
+Overview
+These widgets provide a variety of HTML controls, all of which
are based on <input type="...">. In particular,
the hidden, text, radio and checkbox widgets are currently
-implemented; their use is demonstrated in the acs-templating demo.
The Hidden Widget
This is simply an <input type="hidden">
+implemented; their use is demonstrated in the acs-templating demo.
The Hidden Widget
+This is simply an <input type="hidden">
widget, which is used for passing pre-set variables along with the
-form.
The Text Widget
This widget allows the user to enter one line of text. It is +form.
+The Text Widget
+This widget allows the user to enter one line of text. It is
completely identical to the <input type="text">. The
-html parameter can be used to set its properties
(such as size, maxlength, etc.), as
described in the general widgets reference. The value of this widget is the text
-string.
The Radio Group Widget
This widget actually represents a group of radio buttons, at +string.
+The Radio Group Widget
+This widget actually represents a group of radio buttons, at
most one of which can be selected at any given time. The widget has
one required parameter,
-option option_list, which specifies the
radio buttons to display. The option_list is a list of
-label-value pairs. For example,
+label-value pairs. For example, ++ will create a radio button group with 3 options: "Cheap", whose value is 1000, "Medium", whose value is 50000, and "Expensive", whose value is 999999. The value of the entire widget is either the empty string (if the user did not select any of the radio buttons), or a the value of the currently selected radio button. For instance, if the user selects "Medium" in the example above, the -value oftemplate::element create test_form cost \ -label "Car Cost" -datatype number -widget radio \ -options { {Cheap 1000} {Medium 50000} {Expensive 999999} }costwill be50000. +value ofcost+ will be50000+.The default form template renders the Radio Group widget as a column of radio buttons. Since the Radio Group can consist of many HTML controls, the usual formwidget tag cannot be used to position the widget; instead, the formgroup tag must be -used.
The Checkbox Group Widget
This widget is identical in use to the Radio Group widget, but +used.
+The Checkbox Group Widget
+This widget is identical in use to the Radio Group widget, but instead of radio buttons it generates a group of checkboxes, any number of which can be checked at any given time. The
values(plural) property of the corresponding element contains a list of all the checked values; thevalue-(singular) property contains the first element in the list.
templating\@arsdigita.com - +(singular) property contains the first element in the list. +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/widgets/select.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/widgets/select.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/widgets/select.adp 27 Oct 2014 16:40:26 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/widgets/select.adp 25 Aug 2015 18:02:18 -0000 1.2.2.1 @@ -2,16 +2,19 @@{/doc/acs-templating {Templating}} {Templating System Widget Reference: Select} Templating System Widget Reference: Select - - - The Input Widgets
Overview
These widgets provide the single-selection and +
The Input Widgets
+Overview
+These widgets provide the single-selection and multiple-selection HTML controls; their usage is demonstrated in -the acs-templating demo.
The Select Widget
This widget creates a list of choices, only one of which may be +the acs-templating demo.
+The Select Widget
+This widget creates a list of choices, only one of which may be selected at any given time, using the HTML
<select>control. Similarly to the button group widgets, the Select widget has one required parameter,-optionoption_list, which specifies all the possible choices. The option_list -is a list of label-value pairs. For example,+is a list of label-value pairs. For example, ++ will create a widget with 3 choices: "Pepperoni", "Sausage" and "Canadian Bacon". By default, the widget looks like a drop-down "picklist", however, it can be forced to look like a scrollable -vertical list of n elements by using the +vertical list of n + elements by using thetemplate::element create pizza_form topping \ -label "Pizza Topping" -datatype keyword -widget select \ -options { @@ -20,19 +23,23 @@ {{Canadian Bacon} cbacon} }-html { size n }+ parameter.The value of the Select widget is the value of the currently selected choice. If no choice is selected, the value will be the empty string. However, if the widget happens to look like a picklist, most Web browsers automatically select the first option on the list. This behavior may be changed by supplying an extra "null" option. For example, the options for the pizza topic -selection widget shown above could be changed to
++selection widget shown above could be changed to +template::element create pizza_form topping \ -label "Pizza Topping" -datatype keyword -widget select \ -options { @@ -41,15 +48,19 @@ {Sausage sausage} {{Canadian Bacon} cbacon} } -The Multiselect Widget
This widget is similar to the Select widget, but it allows +
The Multiselect Widget
+This widget is similar to the Select widget, but it allows multiple values to be selected. Because of this, the Multiselect widget cannot look like a picklist. By default, the widget looks like a scrollable list of items, which grows up to 8 items in size (in other words, up to 8 items will be shown without the need to scroll). This size can be overwritten with the
-html { size n }-parameter.The
+values(plural) property of the corresponding +parameter.The
values(plural) property of the corresponding element contains a list of all the selected choices; thevalue(singular) property contains the first selected -choice.
templating\@arsdigita.com - +choice. +
+templating\@arsdigita.com Index: openacs-4/packages/acs-templating/www/doc/widgets/table.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/widgets/table.adp,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/widgets/table.adp 27 Oct 2014 16:40:27 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/widgets/table.adp 25 Aug 2015 18:02:18 -0000 1.2.2.1 @@ -2,10 +2,11 @@{/doc/acs-templating {Templating}} {Templating System Widget Reference: Table} Templating System Widget Reference: Table - - - Table Widget
Overview
The table widget facilitates the creation of a dynamic table +
Table Widget
+Overview
+The table widget facilitates the creation of a dynamic table with controls for sorting on any number of columns. The table layout may be based on a standard sitewide style, or on a custom -template.
templating\@arsdigita.com - +template. +
+templating\@arsdigita.com Index: openacs-4/packages/ajaxhelper/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/ajaxhelper/www/doc/index.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/ajaxhelper/www/doc/index.adp 20 Aug 2015 18:41:24 -0000 1.1.2.1 +++ openacs-4/packages/ajaxhelper/www/doc/index.adp 25 Aug 2015 18:02:18 -0000 1.1.2.2 @@ -2,9 +2,8 @@{/doc/ajaxhelper {Ajax Helper}} {Ajax Helper} Ajax Helper - - - Ajax Helper
Hamilton G. Chua (ham\@solutiongrove.com)
+Ajax Helper
+Hamilton G. Chua (ham\@solutiongrove.com)
September 2007
v0.87d
Components :
Prototype v1.5.1 (http://prototype.conio.net/)
@@ -13,12 +12,16 @@ Curvey Corners (http://www.curvycorners.net/)
Yahoo User Interface Library 2.3.0 (http://developer.yahoo.com/yui/)
Dojo Toolkit 0.4 (http://dojotoolkit.com)
-ExtJs 1.1.1 (http://extjs.com)What's New :
0.87d
+ExtJs 1.1.1 (http://extjs.com) +
+What's New :
+0.87d
+
- Uses Lee Denison's template::head code to load javascript sources and cascading style sheets
- Removed Dojo javascript sources, users who would like to use dojo should download it separately from http://dojotoolkit.org
- Added ExtJs javascript sources
- Added helpers for YUI menu, autocomplete and treeview.
- Added ExtJs helpers for Ext.onReady, Ext.Ajax and Ext.MessageBox
- Additional tests in ajaxhelper/www/tests
-+
Introduction :
The Ajax Helper package provides helper Tcl API procs to generate the javascript from the above listed components to @@ -28,11 +31,14 @@ libraries.
Prerequisites :
The ajax helper package must be installed and mounted in /ajax . The installer should automatically mount the ajax helper -in /ajax/ upon installation of the package.Lee Denison's template::head code must be available. This code +in /ajax/ upon installation of the package.
+Lee Denison's template::head code must be available. This code will soon be committed to CVS head after consulting the community -and some more testing.
In the mean time, you can find the files you need to implement +and some more testing.
+In the mean time, you can find the files you need to implement template head from packages/ajaxhlper/www/docs. You should copy the -files into the following locations
+files into the following locations +
+
openacs_root/packages/acs-templatng/tcl/ @@ -50,85 +56,131 @@ - openacs_root/www/ +
+ As of 0.87d, all required sources and stylesheets are loaded -automatically using Lee Denison's template::head code.
Javascript Sources :
Ajax Procedures :
-Prototype has a pair of javascript functions that alllow +automatically using Lee Denison's template::head code.
+
+Ajax Procedures :
+Prototype + has a pair of javascript functions that alllow programmers to use XMLHTTP. The ajax.updater and ajax.request functions. See http://wiki.script.aculo.us/scriptaculous/show/Ajax.Updater + and http://wiki.script.aculo.us/scriptaculous/show/Ajax.Request -for more information about these javascript functions.
-The Tcl API is used like this+ +for more information about these javascript functions.
+
+ +The Tcl API is used like this
++ The above api will generate an ajax.request javascript function -that is best placed in an event like "onClick".set request [ah::ajaxrequest -url "/url/to/call" -pars "parameter1=parameter_value¶meter1=parameter_value"]+that is best placed in an event like "onClick".
++ Consult the api-doc for more information about other parameters you -can pass on to the ah::ajaxrequest proc.<a href="#" onClick="\@request;noquote\@">Send Request</a>
+can pass on to the ah::ajaxrequest proc.
+
+ The ah::ajaxrequest will make an xmlhttp call but does not do anything about the response. To update content based on the response from an xmlhttp request, use ah::ajaxupdate. This procedure will not only make an xmlhttp call but update the contents of a div or layer with the response text of the xmlhttp -request.
-Here's an example :++request.
+
+ +Here's an example :
+-On the adp side, you can just putset js_update_connections [ah::ajaxupdate -container "connections" \ -url "/url/to/call \ -enclose \ -pars "'effects=$effects&limit_n=$limit_n'" \ -effect "Fade" \ -effectopts "duration: 0.5"]++ +On the adp side, you can just put
+<a href="#" onClick="\@js_update_connections;noquote\@">Update</a> -
+
+ The "-enclose" parameter tells the procedure to enclose the resulting script in script tags <script></script>. This is another option in addition to putting the scripts in html event -attributes like onClick, onMouseover or onChange.
+attributes like onClick, onMouseover or onChange.
+
+ The "-pars" parameter is where you pass the querystring that you want to send along with the xmlhttp request. Notice that it takes the form of a querystring that you normally see in the address bar of your browser. Use this to pass values to the URL you are making -an xmlhttp request to.
+an xmlhttp request to.
+
+ The "-effect" parameter is an optional parameter that allows you to specify the effect you want to execute after the container's -content has been updated.
Cinematic Effects :
-Use ah::effects to generate javascript that allows you +content has been updated.
+
+Cinematic Effects :
+ +Use ah::effects to generate javascript that allows you to implement transitional and cinematic effects to html elements. You will need to consult the scriptaculous documentation http://wiki.script.aculo.us/scriptaculous/tags/effects + to know what kinds of effects and what kinds of options you can -pass to the effect script.
+pass to the effect script.
+
+ The procedure is called in this manner in the tcl file:set effect [ah::effect -element "container" -effect "Fade" -options "duration: 1.5"] -On the adp file you must put the javascript on a click event
++On the adp file you must put the javascript on a click event
+<a href="#" onClick="\@effect;noquote\@">Show Effect</a>
-NOTE :
+NOTE :
The Effect name and the options are case sensitive.
DHTML Callouts :
There is currently basic support for overlibmws. Right now we are able to create bubble type call outs.
-In your tcl file ...+In your tcl file ... +-The adp file should have something like this ....set onmouseover [ah::bubblecallout -text " Contents of My Popup" ]++ +The adp file should have something like this ....
+<a href="#" \@onmouseover;noquote\@ >Link with Popup</a>
-
Drag and Drop Sortables :
- Sortables are documented in the scriptaculous wiki -http://wiki.script.aculo.us/scriptaculous/show/Sortables.
+
+Drag and Drop Sortables :
+ + Sortables are documented in the scriptaculous wiki +http://wiki.script.aculo.us/scriptaculous/show/Sortables. +
+ For sortables to work you will need to define a container which -will hold the elements you want to be sortable.
-Here is what the script looks like+will hold the elements you want to be sortable.
+
+ +Here is what the script looks like
++ You adp page should contain a div with id attribute container. This "container" should have subcontainers which the above script will make sortable. - Index: openacs-4/packages/assessment/www/doc/as_items.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/as_items.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/as_items.adp 20 Aug 2015 17:36:20 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/as_items.adp 25 Aug 2015 18:02:18 -0000 1.1.2.2 @@ -2,55 +2,64 @@append scripts [ah::sortable -element "container" -options "tag:'div',only:'portlet',overlap:'horizontal',constraint:false,ghosting:false"]{/doc/assessment {Assessment}} {As_Items} As_Items - - - Overview
The As_Item and Section catalogues +
+Overview
+The As_Item and Section catalogues are central parts of the assessment system. These repositories support reuse of Assessment components by storing of the various as_items (or questions if you like) and groups of as_items (e.g. Sections) that can be used in an assessment. You are able to add/edit/delete an as_item of a certain type to a certain scope. Furthermore it allows you to search and browse for questions for inclusion in your assesment as well as import and export multiple -questions using various formats.
In this description here we will only +questions using various formats.
+In this description here we will only discuss the design implications for as_items. Green colored tables -have to be internationlized.
Each as_item consists of a specific +have to be internationlized.
+Each as_item consists of a specific as_item Type like "Multiple Choice Question" or "Free Text". Each -as_item Type adds additional +as_item Type adds additional Attributes to the as_item, thereby making it pretty flexible. -Additionally each as_item has a related display type storing information on how to +Additionally each as_item has a related display type storing information on how to display this as_item. This way we can create an adp-snippet which we can include to display a certain as_item (the snippet is stored de-normalized in the as_items table and update on every change to the as_item or the as_item_type).
-How is this achieved concretely? Each +
+How is this achieved concretely? Each as_item Type has it's own table with attributes useful for this as_item type. All tables (as_items, as_item_type_*, as_item_display_*) are controlled by the content repository. Each as_item is linked using acs-relationships to the specific items of the as_item_type_* and as_item_display_* tables. Each as_item can only be linked to one as_item_type instance and one as_item_display instance.
-Categorization and internationalization +
+Categorization and internationalization will make it into OpenACS 5.2, therefore we are not dealing with it in Assessment seperately but use the (to be) built in functionality -of OpenACS 5.2
Additionally we have support functionality +of OpenACS 5.2
+Additionally we have support functionality for an as_item. This includes the help functionality. To give Assessment authors flexibility in adapting as_item defaults, help messages, etc for use in different Assessments, we abstract out a number of attributes from as_items into mapping tables where "override" values for these attributes can optionally be set by authors. If they choose not to set overrides, then the values -originally created in the as_item supercede.
Seperately we will deal with Checks on +originally created in the as_item supercede.
+Seperately we will deal with Checks on as_items. These will allow us to make checks on the input (is the value given by the user actually a valid value??), branches (if we display this as_item, which responses have to have been given) and post-input checks (how many points does this answer -give).
Here is the graphical schema for the +give).
+Here is the graphical schema for the as_item-related subsystems, including the as_item Display subsystem -described here.
-
Core Function: as_items
-
- +described here.
++
Core Function: as_items
+
+
- as_items are the "questions" that constitute the atomic focus of the Assessment package. Each as_item @@ -93,8 +102,10 @@ as_item.
- Admin: Author can reuse, change and give permission on this as_item
-As_item -Types
+ +As_item +Types
+ as_item Types (as_item_type_*) define types of as_items like "Open Question", "Calculation" and others. The as_item type will also define in what format the answer should be @@ -108,9 +119,11 @@ scale), by linking different questions with the answer possibilities (and the same attributes) to one as_item_type object. If we have objects that are linked this way, we can generate the -matrix for them easily. A functional list of all +matrix for them easily. + A functional list of all as_item types and their attributes can be found in the -requirements section.+requirements section. +
- Open Question (as_item_type_oq):
- -
- as_item_type_id
@@ -128,7 +141,8 @@ else.- allow_negative_p: This will allow a negative percentage as well (as the total result).
+
+-
- Short Answer Answers (as_item_sa_answers):
@@ -144,7 +158,8 @@ relationship.
+
+-
- Multiple Choice Item (as_item_type_mc)
@@ -159,7 +174,8 @@ (correct and incorrect). Check if enough choices are available.+
+-
- Multiple Choices @@ -212,7 +228,8 @@ cr_revisions
+
+-
- Image Map Choices (as_item_image_choices):
@@ -230,22 +247,27 @@ String that defines the html area coordinates if this choice is used in an image_map question.Item Display Types
Each item has an item_display_type object + +Item Display Types
+Each item has an item_display_type object associated with it, that defines how to display the item. Each item_display_type has a couple of attributes, that can be passed to the formbuilder for the creation of the widget. Each widget has at least one item_display_type associated with it. In the long run I think this system has the potential to become a part of OpenACS itself (storing additional display information for each acs_object), but we are not there yet :). Obviously we are talking -cr_item_types here as well.Each item_display_type has a couple of -attributes in common.
+cr_item_types here as well.
+Each item_display_type has a couple of +attributes in common.
+
- item_display_id
- cr::name - name like "Select box, aligned right", stored in the name field of CR.
- html_display_options - field to specify other stuff like textarea dimensions ("rows=10 cols=50" eg)
-Depending on the presentation_types + +
+Depending on the presentation_types additonal attributes (presentation_type attributes) come into play (are added as attributes to the CR item type) (mark: this is not feature complete. It really is up @@ -254,7 +276,8 @@ mentioning all HTML possibilities associated with each type (e.g. a textarea has width and heigth..) as these can be parsed in via the html_display_options.
-+
- textbox (as_item_display_tb) - single-line typed entry
@@ -428,22 +451,27 @@ are textboxes for all-keyboard entry; needs no resetting scripts but does need date validity check
- file_upload - present a File box (browse button, file_name textbox, and submit button together) so user can upload a file
-Help System
The help system should allow a small "?" + +Help System
+The help system should allow a small "?" appear next to an object's title that has a help text identified with it. Help texts are to be displayed in the nice bar that Lars created for OpenACS in the header. Each object can have multiple help texts associated with it (which will be displayed in sort order with each hit to the "?".) and we can reuse the help text, making this an n:m relationship (using cr_rels). E.g. you might want to have a default help text for certain cr_as_item_types, -that's why I was thinking about reuse...Relationship attributes:
+that's why I was thinking about reuse...
+Relationship attributes:
+
- as_item_id
- message_id - references as_messages
- sort_order (in which order do the messages appear)
-+ +
+Messages (as_messages) abstracts out help messages (and other types of messages) for use in this -package. Attributes include:
+package. Attributes include:
- Index: openacs-4/packages/assessment/www/doc/as_types.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/as_types.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/as_types.adp 20 Aug 2015 17:36:21 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/as_types.adp 25 Aug 2015 18:02:18 -0000 1.1.2.2 @@ -2,10 +2,10 @@
- message_id
- message
{/doc/assessment {Assessment}} {Item Types and Item Display Types} Item Types and Item Display Types - - - Overview
What to do to add new item types or item -display types:
+
+Overview
+What to do to add new item types or item +display types:
+- Index: openacs-4/packages/assessment/www/doc/data-modell.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/data-modell.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/data-modell.adp 20 Aug 2015 17:36:21 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/data-modell.adp 25 Aug 2015 18:02:18 -0000 1.1.2.2 @@ -2,30 +2,34 @@
- add new table to assessment-item-types-create.sql
- add entry to matrix table item_type -> display_type in assessment-types-create.sql
- add content type data to @@ -19,4 +19,3 @@ www/admin/item-edit-display-$$
- add pages to display data: lib/item-show-$$ or lib/item-show-display-$$
{/doc/assessment {Assessment}} {Assessment Data Modell Overview} Assessment Data Modell Overview - - - Overview
At its core, the Assessment package defines a hierarchical +
Overview
+At its core, the Assessment package defines a hierarchical container model of a "survey", "questionnaire" or "form". This approach not only follows the precedent of existing work; it also makes excellent sense and no one has come up with a better -idea.
+idea. +
+
- One Assessment consists of
- One or more Sections which each consist of
- One or more Items which have
- Zero or more Choices
-We choose the terms Assessment-Sections-Items-Choices over +
We choose the terms Assessment-Sections-Items-Choices over Surveys-Sectdions-Questions-Choices partly to reduce naming clashes during the transition from Survey/Questionnaire packages, but mostly because these terms are more general and thus suit the -broader applicability intended for this package.
As is the custom in the OpenACS framework, all RDBMS tables in +broader applicability intended for this package.
+As is the custom in the OpenACS framework, all RDBMS tables in the package will be prepended with "as_" to prevent further prefent naming clashes. Judicious use of namespaces will also be made in -keeping with current OpenACS best practice.
Several of the Metadata entities have direct counterparts in the +keeping with current OpenACS best practice.
+Several of the Metadata entities have direct counterparts in the Data-related partition of the data model. Some standards (notably CDISC) rigorously name all metadata entities with a "_def" suffix and all data entities with a "_data" suffix -- thus "as_item_def" and "as_item_data" tables in our case. We think this is overkill since there are far more metadata entities than data entities and in only a few cases do distinctions between the two become important. In those cases, we will add the "_data" suffix to data -entities to make this difference clear.
A final general point (that we revisit for specific entities +entities to make this difference clear.
+A final general point (that we revisit for specific entities below): the Assessment package data model exercises the Content Repository (CR) in the OpenACS framework heavily. In fact, this use of the CR for most important entities represents one of the main @@ -37,18 +41,22 @@ couple column names in our derived tables because of naming clashes with columns in cr_items and cr_revisions: title and description. Furthermore we can handle versioning -and internationalization through the CR.
Synopsis of The Data Model
Here's a detailed summary view of the entities in the Assessment +and internationalization through the CR.
+Synopsis of The Data Model
+Here's a detailed summary view of the entities in the Assessment package. Note that in addition to the partitioning of the entities between Metadata Elements and Collected Data Elements, we identify the various subsystems in the package that perform basic functions.
+ We discuss the following stuff in detail through the subsequent pages, and we use a sort of "bird's eye view" of this global graphic to keep the schema for each subsystem in perspective while homing in on the relevent detail. Here's a brief introduction to -each of these section+each of these section
+
+
- -core - items entities (purple) +core - items entities (purple) define the structure and semantics of Items, the atomic units of the Assessment package
- core - grouping entities (dark @@ -60,19 +68,19 @@ scoring ("grading") entities (yellow-green) define how raw user responses are to be processed into calculated numeric values for a given Assessment
- -display entities (light blue) +display entities (light blue) define constructs that handle how Items are output into the actual html forms returned to users for completion -- including page layout and internationalization characteristics
- scheduling entities define mechanisms for package administrators to set up when, who and how often users should perform an Assessment
- -session data collection +session data collection entities (bright green) define entities that store information about user data collection events -- notably session status and activities that change that status as the user users the system
-+ - Index: openacs-4/packages/assessment/www/doc/data_collection.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/data_collection.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/data_collection.adp 20 Aug 2015 17:36:21 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/data_collection.adp 25 Aug 2015 18:02:18 -0000 1.1.2.2 @@ -2,31 +2,34 @@
{/doc/assessment {Assessment}} {Data Collection} Data Collection - - - Overview
The schema for the entities that actually collect, store and +
Overview
+The schema for the entities that actually collect, store and retrieve Assesment data parallels the hierarchical structure of the Metadata Data Model. In the antecedent "complex survey" and "questionnaire" systems, this -schema was simple two-level structure:
+schema was simple two-level structure: +
+
- survey_responses which capture information about which survey was completed, by whom, when, etc
- survey_question_responses which capture the actual user data in a "long skinny table" mechanism
-This suffices for one-shot surveys but doesn't support the fine +
This suffices for one-shot surveys but doesn't support the fine granularity of user-action tracking, "save&resume" capabilities, and other requirements identified for the enhanced Assessment package. Consequently, we use a more extended -hierarchy:
+hierarchy: +
+
- Assessment Session which captures information about which Assessment, which Subject, when, etc
- Section Data which holds information about the status of each Section
- Item Data which holds the actual data extracted from the Assessment's html forms; this is the "long skinny table"
-To support user modification of submitted data (of which +
To support user modification of submitted data (of which "store&resume" is a special case), we base all these entities in the CR. In fact, we use both cr_items and cr_revisions in our schema, since for any given user's Assessment submission, there @@ -35,7 +38,8 @@ versions of the Assessment. While this situation may be unusual, the fact that it must be supported means that the semantics of cr_items don't fit the Assessment itself. They do fit the -semantics of a given user's Assessment "session" however.
We distinguish here between "subjects" which are users whose +semantics of a given user's Assessment "session" however.
+We distinguish here between "subjects" which are users whose information is the primary source of the Assessment's responses, and "users" which are real OpenACS users who can log into the system. Subjects may be completing the Assessment themselves or may @@ -49,8 +53,10 @@ identical to the subject_id. But if the user completing the assessment is doing it by proxy for the "real" subject, then the staff_id will be hers while the subject_id will belong to the -"real" subject.
We've simplified this subsection of Assessment considerably from -earlier versions, and here is how and why:
+"real" subject. +
+We've simplified this subsection of Assessment considerably from +earlier versions, and here is how and why:
+
- Annotations: We previously had a separate table to capture any type of ad hoc explanations/descriptions/etc that a @@ -137,12 +143,18 @@ Workflow. Assessment authors will have a UI through which they can configure an applicable workflow (defining states, roles, actions) for the assessment.
-Synopsis of Data-Collection Datamodel
Here's the schema for this subsystem:
-
Specific Entities
This section addresses the attributes the most important +
Synopsis of Data-Collection Datamodel
+Here's the schema for this subsystem:
+
++
Specific Entities
+This section addresses the attributes the most important entities have in the data-collection data model -- principally the various design issues and choices we've made. We omit here literal SQL snippets since that's what the web interface to CVS is for. -;-)
+;-) +
+
- Assessment Sessions (as_sessions) are the top of the data-collection entity hierarchy. They provide the central @@ -224,7 +236,8 @@ to attach a reply to a student's answer to a specific Item or make a global comment about the entire Assessment. This will be achieved by using the General Comments System of OpenACS
-+
- +
- Signing of content allows to verify that the data submitted is actually from the person it is pretended to be from. This assumes an public key @@ -235,5 +248,5 @@ as_item_data is actually verified the system only has to check the signed_data with the public key and see if it matches the data.
-
- +
Index: openacs-4/packages/assessment/www/doc/display_types.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/display_types.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/display_types.adp 20 Aug 2015 17:36:21 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/display_types.adp 25 Aug 2015 18:02:18 -0000 1.1.2.2 @@ -2,28 +2,32 @@{/doc/assessment {Assessment}} {As_Item Display Types} As_Item Display Types - - - Overview
Displaying items to users has a couple of +Overview
+Displaying items to users has a couple of challanges. First of all the display of a single item can be different for each item_type (and even within a type). Second of all, the display of items within a section can be different from assessment to assessment. Last but not least, the whole assessment might be displayed differently depending on attributes and the type -of assessment we are talking about.Note: please refer to the discussion -of Items here. That discussion +of assessment we are talking about. +
Note: please refer to the discussion +of Items here. That discussion complements the discussion here, and the data model graphic pertaining to the Item Display Types system is available there -also.
Item Display Types
Each item has an item_display_type object +also. +Item Display Types
+Each item has an item_display_type object associated with it, that defines how to display the item. Each item_display_type has a couple of attributes, that can be passed to the formbuilder for the creation of the widget. Each widget has at least one item_display_type associated with it. In the long run I think this system has the potential to become a part of OpenACS itself (storing additional display information for each acs_object), but we are not there yet :). Obviouslly we are talking -cr_item_types here as well.Each item_display_type has a couple of -attributes in common.
+cr_item_types here as well.
+Each item_display_type has a couple of +attributes in common.
+
- item_display_type_id
- item_type_name - name like "Select box, aligned right", stored in the name field of CR.
- presentation_type - the type of "widget" @@ -50,14 +54,16 @@ defaults that ad_dateentrywidget expects: "" for "no date", "0" for "today", or else some specific date set by the author; see this example)
-Depending on the presentation_types additonal +
Depending on the presentation_types additonal attributes (presentation_type attributes) come into play (are added as attributes to the CR item type) (mark: this is not feature complete. It really is up to the coder to decide what attributes each widget should have, down here are only *suggestions*). Additionally we're not mentioning all HTML possibilities associated with each type (e.g. a textarea has width -and heigth..).
+and heigth..). +
++
- textbox - single-line typed entry
- abs_size - An abstraction of the real size value in "small","medium","large". Up to the developer how this @@ -109,23 +115,29 @@ but does need date validity check
- image_map - requires a linked image; the image map coordinates are handled as Item Choices
- file_upload - present a File box (browse button, file_name textbox, and submit button together) so user can upload a file
- many more
-In addition, there are some potential presentation_types that +
In addition, there are some potential presentation_types that actually seem to be better modeled as a Section of separate -Items:
+Items: +
+
- ranking - a set of alternatives each need to be assigned an exclusive rank ("Indicate the order of US Presidents from bad to worse"). Is this one Item with multiple Item Choices? Actually, not, since each alternative has a value that must be separately stored (the tester would want to know that the testee ranked GWB last, for instance).
- ...
-Section +
Section display
+ A section can be seen as a form with all the items within this section making up the form. Depending on the type of assessment we are talking about, the section can be displayed in various ways.
+ The section display page will be made up of the following -attributes:+attributes:
++ Additionally each section has certain parameters that determine the look and feel of the section itself. Luckily it is not necessary to have differing attributes for the sections, therefore all these display attributes can be found with the section and assessment specification - Index: openacs-4/packages/assessment/www/doc/grouping.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/grouping.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/grouping.adp 20 Aug 2015 17:36:21 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/grouping.adp 25 Aug 2015 18:02:18 -0000 1.1.2.2 @@ -2,12 +2,13 @@
- Name: text. Name of the section like "test view sorted"
- Number of questions per page: integer. THIS HAS TO BE CHANGED IN THE DATAMODELL FROM PAGINATION_STYLE. How many questions shall be displayed per page in this section. Usually the answer would be @@ -154,8 +166,8 @@ submitted will be treated as not being submitted at all.
{/doc/assessment {Assessment}} {Assessment} Assessment - - Here is a graphical overview of the subsystem in the Assessment package that organizes Items into Sections and whole Assessments:
-
Review of Specific Entities
+ +
- Index: openacs-4/packages/assessment/www/doc/page_flow.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/page_flow.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/page_flow.adp 20 Aug 2015 17:36:21 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/page_flow.adp 25 Aug 2015 18:02:18 -0000 1.1.2.2 @@ -2,34 +2,39 @@+
Review of Specific Entities
+
- Assessments (as_assessments) are the highest-level container in the hierarchical structure. They define the key by which all other entities are assembled into meaningful order during display, @@ -77,7 +78,8 @@ special style associated with it. As styles can be reused (e.g. within a department) they are covered in the as_assessment_styles:
-+
+- Index: openacs-4/packages/assessment/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/index.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/index.adp 20 Aug 2015 17:36:21 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/index.adp 25 Aug 2015 18:02:18 -0000 1.1.2.2 @@ -2,17 +2,18 @@
- custom_header - Custom header (and footer) that will be @@ -211,4 +213,3 @@
{/doc/assessment {Assessment}} {Assessment Overview} Assessment Overview - - - Introduction
The Assessment Package unites the work and needs of various +
Introduction
+The Assessment Package unites the work and needs of various members of the OpenACS community for data collection functionality within the OpenACS framework. We're using the term "Assessment" instead of "Survey" or "Questionnaire" (or "Case Report Form" aka CRF, the term used in clinical trials) because it is a term used by IMS and because it connotes the more generic nature of the data -collection system we're focusing on.
There has been considerable recent interest in expanding the +collection system we're focusing on.
+There has been considerable recent interest in expanding the capabilities of generic data collection packages within OpenACS. -Identified applications include:
+Identified applications include: +
+
- Educational settings. The dotLRN project has updated the Simple-Survey package to the Survey package now in the current distribution. A number of groups in the OpenACS community are @@ -49,8 +50,11 @@ key to creation of new vertical-application tools like dotWRK. Such integration would also be immensely useful for a clinical trials management toolkit.
-Historical Considerations (Work Done So Far)
Several OpenACS efforts form the context for any future work. -These include:
+
+Historical Considerations (Work Done So Far)
+Several OpenACS efforts form the context for any future work. +These include:
+
- Survey. This package (largely written/revised by Dave Bauer) doesn't currently have any documentation in the documentation section of the OpenACS.org site, but it is in any current OpenACS installation at /doc/survey/. Dave has @@ -94,46 +98,62 @@ will need a substantial rewrite to work within the new 5.x infrastructure.
- Simple-survey. This package remains in the OpenACS distribution but it is now obsolete, supplanted by Survey
-Competitive Analysis
+Competitive Analysis
+ The number of competing products in this area is *huge*. Starting with the usual suspects Blackboard and WebCT you can go on to clinical trial software like Oracle Clinical or specialised survey systems. When writing the specifications we tried to incorporate as many ideas as possible from the various systems we had a look at and use that experience. A detailed analysis would be too much for -the moment.Functional Requirements
-An overview of the functional requirements can be found here. It is highly encouraged to be read +the moment.
+Functional Requirements
+ +An overview of the functional requirements can be found here +. It is highly encouraged to be read first, as it contains the use cases along with a global overview of the functionality contained within assessment. Additional requirements can be found in the specific pages for the user -interface.Design Tradeoffs
+interface.
+Design Tradeoffs
+ The assessment system has been designed with a large flexibility and reuse of existing functionality in mind. This might result in larger complexity for simple uses (e.g. a plain poll system on it's own will be more performant than running a poll through assessment), but provides the chance to maintain one code base for -all these seperate modules.API
-The API will be defined during the development phase.Data model
-The data model is described in detail in the design descriptions.User Interface
+all these seperate modules.
+API
+ +The API will be defined during the development phase.
+Data model
+ +The data model is described in detail in the design descriptions +.
+User Interface
+ The UI for Assessment divides into a number of primary functional -areas, with the entry page located here. It is split up into multiple -sections:+areas, with the entry page located here +. It is split up into multiple +sections:
+
+
- -Assessment +Assessment Authoring: all the pages involved in creating, editing, and deleting the Assessments themselves
- -Section +Section Authoring: all the pages involved in creating, editing, and deleting the Sections themselves. Includes the page to browse for items to include in sections
- -Item Authoring and +Item Authoring and Catalogue: all the pages involing the item creation and the item catalogue.
- -Assessment +Assessment Delivery: all the pages involved in deploying a given Assessment to users for completion, processing those results, etc; these are user pages
- -Section on Tests: +Section on Tests: Currently still split away, some notes on additional user interface for test. Shall be integrated with the rest of the pages.
- Assessment Review: all the pages involved in select data extracts and displaying them in whatever formats indicated; this @@ -148,13 +168,21 @@ be further thought through, depending on where the Site Management mechanisms reside.
- Triggers and Action Execution
-
-The Page Flow page is diagrammed +
+ +The Page Flow + page is diagrammed below and should give a very rough and outdated overview, but still -good for getting an impression.Authors
+good for getting an impression.
+
+Authors
+ The specifications for the assessment system have been written by Stan -Kaufman and Malte -Sussdorff with help from numerous people within and outside the -OpenACS community.
- +Kaufman + and Malte +Sussdorff + with help from numerous people within and outside the +OpenACS community.
+
Index: openacs-4/packages/assessment/www/doc/item_types.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/item_types.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/item_types.adp 20 Aug 2015 17:36:21 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/item_types.adp 25 Aug 2015 18:02:18 -0000 1.1.2.2 @@ -2,18 +2,20 @@{/doc/assessment {Assessment}} {AS_item Types} AS_item Types - - Overview
-This is a list of item types and some of their attributes we want to + +This is a list of item types and some of + their attributes we want to support (a full list is stored with the design specifications). At a later stage we are going to add the checks for each item_type to this page as well. This does not mean we are going to create all of them in the first shot. The attributes are *ONLY* those which are not already part of as_items and therefore should be dealt with in -as_item_type_attributes (see Item Data -Model for reference). -Specific Item Types
+as_item_type_attributes (see Item Data +Model + for reference). +
+ Only site wide admins will get to see the following question types:Specific Item Types
+
- Open Question
Open questions are text input questions for free text. For obvious reasons they cannot be auto corrected. The difference @@ -206,6 +208,7 @@
- Database question:
The answer to this question will be stored in the database. The @@ -223,4 +226,3 @@ matches the user_id of the respondee.
{/doc/assessment {Assessment}} {Page Flow} Page Flow - - - Overview
Through the OpenACS templating system, the UI look&feel will +
Overview
+Through the OpenACS templating system, the UI look&feel will be modifiable by specific sites, so we needn't address page layout and graphical design issues here. Other than to mention that the -Assessment package will use these OpenACS standards:
+Assessment package will use these OpenACS standards: +
+
- "trail of breadcrumb" navigational links
- context-aware (via user identity => permissions) menu options (whether those "menus" are literally menus or some other interface widget like toolbars)
- in-place, within-form user feedback (eg error messages about a form field directly next to that field, not in an "error page")
-Furthermore, the set of necessary pages for Assessment are not +
Furthermore, the set of necessary pages for Assessment are not all that dissimilar to the set required by any other OpenACS package. We need to be able to create, edit and delete all the constituent entities in the Package. The boundary between the pages belonging specifically to Assessment and those belonging to "calling" packages (eg dotLRN, clinical trials packages, financial management packages, etc etc) will necessarily be somewhat -blurred.
Proposed Page Flow
Nevertheless, here is a proposed set of pages along with very +blurred.
+Proposed Page Flow
+Nevertheless, here is a proposed set of pages along with very brief descriptions of what happens in each. This organization is actually derived mostly from the existing Questionnaire module which can be examined here in the "Bay Area OpenACS Users Group (add yourself to the group and -have a look).
The UI for Assessment divides into a number of primary -functional areas, as diagrammed below. These include:
+have a look). +
+The UI for Assessment divides into a number of primary +functional areas, as diagrammed below. These include:
++ In addition to the page flow we have two types of portlets for -.LRN:
- the "Home" area (for lack of a better term). These are the main index pages for the user and admin sections
- -Assessment +Assessment Authoring: all the pages involved in creating, editing, and deleting the Assessments themselves; these are all admin pages
- Assessment Delivery: all the pages involved in deploying a given Assessment to users for completion, processing those results, @@ -51,23 +56,28 @@ Trials Management CTM system would. But we include this in our diagram as a placeholder.
+.LRN:
+-More Ideas:
- Portlet for the respondee with all assessments that have to be answered and their deadlines.
- Portlet for staff with all assessments that have to be reviewed with review deadline and number of responses still to look at.
+ +More Ideas:
+
+
- Possibility to browse assessments and sections by category.
- -
+
+
- -
So this is how we currently anticipate this would all interrelate:+ - Index: openacs-4/packages/assessment/www/doc/policies.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/policies.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/policies.adp 20 Aug 2015 17:36:22 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/policies.adp 25 Aug 2015 18:02:19 -0000 1.1.2.2 @@ -2,10 +2,9 @@
{/doc/assessment {Assessment}} {Policies and Events} Policies and Events - - Policies and Events
-+ +
- Index: openacs-4/packages/assessment/www/doc/requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/requirements.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/requirements.adp 20 Aug 2015 17:36:22 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/requirements.adp 25 Aug 2015 18:02:19 -0000 1.1.2.2 @@ -2,12 +2,13 @@
- Assessment-Policies (as_assessment_policies) abstract out from Assessments a variety of attributes that describe deployment particulars. This allows multiple users of an Assessment to define @@ -46,4 +45,3 @@
{/doc/assessment {Assessment}} {Assessment functional requirements} Assessment functional requirements - - Introduction
+ The assessment module provides OpenACS with capabilities to conduct surveys, tests and dynamic information gathering in general, as can -be seen in the use cases.Vision Statement
+be seen in the use cases.
+Vision Statement
+ The motivation behind the Assessment package is to extend the functionality of the existing Survey package in both depth and breadth: @@ -18,21 +19,27 @@ OpenACS packages and to assemble larger systems of packages within which Assessment is one component (eg dotLRN, clinical trials management systems, etc) -The current Survey package is a very capable piece of +
The current Survey package is a very capable piece of engineering that provides stand-alone data collection functions. It is subsite-aware and has been integrated to some extent with portlets. It also is just being integrated into user registration processes. These efforts point the path down which the Assessment -package intends to proceed to its logical conclusion.
Development efforts for Assessment thus involve two tracks:
+package intends to proceed to its logical conclusion. +
+Development efforts for Assessment thus involve two tracks:
+
- refinement and extension of the data model and UIs from Survey (and its sibling forks) to support a variety of expanded user requirements
- incorporation of hooks (of various sorts, such as Service Contracts) to integrate Assessment with OpenACS subsystems: Content Repository, Workflow, Notifications, Internationalization, etc
-The measure of success of the Assessment package is the ease +
The measure of success of the Assessment package is the ease with which it can rapidly be deployed into some high-profile implementations, notably dotLRN and a clinical trials management -system under development.
Use Cases
+system under development. +Use Cases
+ The assessment module in it's simplest form is a dynamic information gathering tool. This can be clearly seen in the first group of use cases, which deal with surveys (one form of @@ -50,23 +57,31 @@ let the user fill out correct answers to questions, if the question is not used in a test). Some use cases like elections require special parameters not necessary anywhere else (like counting -system).Survey scenario
+system). +Survey scenario
+ The survey scenarios are the basic use cases for the use of the -assessment system.Simple survey
+assessment system.
+Simple survey
+ An editor wants to conduct surveys on his site. For this purpose he creates questions which are stored in a question catalogue. From this question catalogue, the editor choose the questions he wants to use in his current survey along with the style the survey should be presented to the user. Once satisfied he can make the survey public or test it first. Once the survey is public subjects (users) of the site can take the survey by filling out the generated form -with all the questions the author added to the survey.Quality Assurance
+with all the questions the author added to the survey.
+Quality Assurance
+ A company wants to get feedback from users about it's product. It creates a survey which offers branching (to prevent users from filling out unnecessary data, e.g. if you answered you have never been to Europe the question "Have you seen Rome" should not show up) and multi-dimensional likert scales (To ask for the quality and -importance of a part of the product in conjunction).Professional data entry
+importance of a part of the product in conjunction).
+Professional data entry
+ A clinic wants to conduct a trial. For this research assistants are asked to interview the patients and store the answers in the assessment on behalf of the client. For meeting FDA requirements it @@ -78,13 +93,15 @@ digits, if the age of the patient is below 10, no need to ask for credit card information, ...).University survey
+ A Professor wants to create a test by searching through the question database and selecting old questions. He searches the database for a specific keyword or browses by category. The System presents him all questions which have the keyword and/or category in it. The Professor is able to preview every question and may then decide which question he will transfer into the survey.Internal Evaluation
+ An institution wants to survey students to compare the quality of specific courses, teachers, or other factors effecting the quality of their education and level of happiness. It should be possible @@ -93,7 +110,9 @@It should also be able to show the results of a survey to a group of users (e.g. a specific department evaluated). The results should be able to be displayed in a way that give a department a -ranking compared with other departments.
Reuse of questions
+ranking compared with other departments. +Reuse of questions
+ The author of multiple choice question decides that the provided answers are not good for differentiating the knowledge of the subjects and changes some of them. All editors using this question @@ -105,6 +124,7 @@ question already, that it has changed (and that they might (have to) re-answer).Multiple languages
+ The quality assurance team of the company mentioned above realizes that the majority of it's user base is not native English speakers. This is why they want to add additional translations to the @@ -114,30 +134,35 @@ language used along with the response (as a translation might not be as good as the original).The poll
+ An editor wants to conduct a poll on the site with immediate publication of the result to get a feeling how users like the new design of the website. The result can be displayed in an includelet (see the below for details) on any page the editor wants.The election
+ The OpenACS community wants to conduct a new election on the OCT. On creation the names of the contestants have to be available along with a list of all users allowed to vote. Depending on the election system, the users have one or multiple votes (ranked or not), which are calculated in a certain way. Once the election is over the result is published.Collective Meeting planing
+ The sailing club needs to find meeting time for all skippers to attend. Given a number of predefined choices, each skipper can give his/her preference for the time slots. The slot with the highest approval wins and is automatically entered into the calendar of all skippers and a notification send out.Testing scenario
+ Especially in the university environment it is important to be able to conduct tests. These help the students to prepare for exams but also allow Professors to conduct exams. In addition to the data collection done in a survey scenario testing adds checks and instant evaluation to assessment.Proctored Exam
+ A Professor wants to have a proctored test in a computer room. He wants to create the test using question that he has added and are already in the database. The only people allowed to take the test @@ -155,7 +180,9 @@ sheet which needs the answers to be ticked off. A scanner system scans this return sheet and stores the data for the student in the system. -The Mistake
+The Mistake
+ A Professor has created a test from the question pool and have administered the exam to a group of students. The test has been taken by some of his students already. He discovers that the answer @@ -165,6 +192,7 @@ taken the test and received a grade that their results have changed.Discriminatory power
+ A Professor has created a test which is taken by all of his students. The test results should be matched with the individual results to create the discriminatory power and the reliability of @@ -181,7 +209,9 @@ answered by good students more often right than by bad students. If the questions is answered same often by good and bad students the discriminatory power tells the professor that the question is more -to guess than to know]The vocabulary test
+to guess than to know] +The vocabulary test
+ A student wants to learn a new language. While attending the class, he enters the vocabulary for each section into the assessment system. If he wants to check his learned knowledge he takes the @@ -195,18 +225,22 @@+ To determine the correct answer it is possible to do a char-by-char compare and highlight the wrong parts vs. just displaying the wrong and correct answer (at the end of the test or once the answer is given).
- Free text translation of a word
- Free text translation of a sentence
- Multiple choice test
- Fill in the blanks
The quizz
+ To pep up your website you offer a quiz, which allows users to answer some (multiple choice) questions and get the result immediately as a percentage score in a table comparing that score to other users. Users should be able to answer only a part of the possible questions each time. If the user is in the top 2%, offer him the contact address of "Mensa", other percentages should give -encouraging text.Scoring
+encouraging text.
+Scoring
+ The computer science department has a final exam for the students. The exam consists of 3 sections. The exam is passed, if the student achieves at least 50% total score. In addition the student has to @@ -220,69 +254,93 @@ get different percentages for each answer. As the computer science department wants to discourage students from giving wrong answers, some wrong answers have a negative percentage (thereby reducing the -total score in the section).Reuse in other packages
+total score in the section).
+
+Reuse in other packages
+ The information gathering capabilities of the assessment system should be able to be reused by other packages.User profiling
+ In order to join a class at the university the student has to fill out some questions. The answers can be viewed by the administrator but also by other students (pending the choice of the user). This latter functionality should not be part of assessment itself, but of a different module, making use of assessment. The GPI user-register is a good example for this.Includes
+ Using a CMS the editor wants to include the poll on the first page on the top right corner. The result should be shown on a separate page or be included in the CMS as well.Information gathering for developers
+ A developer needs functionality for gathering dynamic information easily. For this he should be able to easily include an assessment instead of using ad_form directly in his code. This gives the administrator of the site the option to change the questions at a later stage (take the questions in the user sign-up process as an example).Database questions
+ Some answers to questions should be stored directly in database tables of OpenACS in addition to the assessment system. This is e.g. useful if your questions ask for first_names and last_name. When answering the question, the user should see the value currently stored in the database as a default.Action driven questions
+ The company conducting the QA wants to get more participants to it's survey by recommendation. For this each respondee is asked at the end of the survey if he would recommend this survey to other users (with the option to give the email address of these users). The answer will be processed and an email send out to all given emails inviting them to take the survey. -User Types
There are several types of administrative users and end-users +
User Types
+There are several types of administrative users and end-users for the Assessment package which drive the functional requirements. Here is a brief synopsis of their responsibilities in this -package.
Package-level Administrator
+package. +Package-level Administrator
+ Assigns permissions to other users for administrative roles. -Editor
Has permissions to create, edit, delete and organize in +
Editor
+Has permissions to create, edit, delete and organize in repositories Assessments, Sections and Items. This includes defining Item formats, configuring data validation and data integrity checks, configuring scoring mechanisms, defining -sequencing/navigation parameters, etc.
Editors could thus be teachers in schools, principal +sequencing/navigation parameters, etc.
+Editors could thus be teachers in schools, principal investigators or biostatisticians in clinical trials, creative designers in advertising firms -- or OpenACS developers incorporating a bit of data collection machinery into another -package.
Scheduler
Has permissions to assign, schedule or otherwise map a given +package.
+Scheduler
+Has permissions to assign, schedule or otherwise map a given Assessment or set of Assessments to a specific set of subjects, students or other data entry personnel. These actions potentially will involve interfacing with other Workflow management tools (e.g. an "Enrollment" package that would handle creation of new Parties -(aka clinical trial subjects) in the database.
Schedulers could also be teachers, curriculum designers, site -coordinators in clinical trials, etc.
Analyst
Has permissions to search, sort, review and download data -collected via Assessments.
Analysts could be teachers, principals, principal investigators, -biostatisticians, auditors, etc.
Subject
Has permissions to complete an Assessment providing her own +(aka clinical trial subjects) in the database.
+Schedulers could also be teachers, curriculum designers, site +coordinators in clinical trials, etc.
+Analyst
+Has permissions to search, sort, review and download data +collected via Assessments.
+Analysts could be teachers, principals, principal investigators, +biostatisticians, auditors, etc.
+Subject
+Has permissions to complete an Assessment providing her own responses or information. This would be a Student, for instance, completing a test in an educational setting, or a Patient completing a health-related quality-of-life instrument to track her health status. Subjects need appropriate UIs depending on Item formats and technological prowess of the Subject -- kiosk "one-question-at-a-time" formats, for example. May or may not get -immediate feedback about data submitted.
Subjects could be students, consumers, or patients.
Data Entry Staff
Has permissions to create, edit and delete data for or about the +immediate feedback about data submitted.
+Subjects could be students, consumers, or patients.
+Data Entry Staff
+Has permissions to create, edit and delete data for or about the "real" Subject. Needs UIs to speed the actions of this trained individual and support "save and resume" operations. Data entry procedures used by Staff must capture the identity if both the @@ -294,9 +352,13 @@ requirements for FDA submissions center around mechanisms encountered here: to prove exactly who created any datum, when, whether it is a correct value, whether anyone has looked at it or -edited it and when, etc etc...)
Staff could be site coordinators in clinical trials, insurance -adjustors, accountants, tax preparation staff, etc.
System / Application Overview
-Editing of Assessments
+edited it and when, etc etc...) +
Staff could be site coordinators in clinical trials, insurance +adjustors, accountants, tax preparation staff, etc.
+System / Application Overview
+
+Editing of Assessments
+-
- Manage the structure of Assessments -- the organization of series of questions (called "Items") into Sections (defined logically in terms of branch points and literally in terms of @@ -450,7 +512,9 @@ use.
Scheduling of Assessments
+
+Scheduling of Assessments
+-
- Create, edit, clone and delete Assessment Schedules. Schedulers will define:
@@ -475,7 +539,9 @@ shows expected dates, actual completion dates, etc.
Analysis of Assessments
+
- Provide UIs to: +
Analysis of Assessments
+
- Provide UIs to:
-
- Define time-based, sortable searches of Assessment data (both primary/raw data and calculated Scored data) for tabular and (if @@ -484,7 +550,9 @@ (incomplete assessments, audit trails of changed data values, etc)
Performance of Assessments
+
- Provide mechanisms to: +
Performance of Assessments
+- Index: openacs-4/packages/assessment/www/doc/sequencing.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/sequencing.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/sequencing.adp 20 Aug 2015 17:36:22 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/sequencing.adp 25 Aug 2015 18:02:19 -0000 1.1.2.2 @@ -2,9 +2,8 @@
- Provide mechanisms to:
- Handle user Login (for non-anonymous studies)
- Determine and display correct UI for type of user (eg kiosk format for patients; keyboard-centric UI for data entry Staff)
- Deliver Section forms to user
- Perform data validation and data integrity checks on form @@ -503,4 +571,3 @@ Subject, Staff, Scheduler, or Editor)
{/doc/assessment {Assessment}} {Assessment Item Checks} Assessment Item Checks - - - Sequencing
Along with Data Validation and Versioning, probably the most +
Sequencing
+Along with Data Validation and Versioning, probably the most vexing problem confronting the Assessment package is how to handle conditional navigation through an Assessment guided by user input. Simple branching has already been accomplished in the "complex @@ -15,7 +14,8 @@ branching/skipping depends not merely on what combination of "correct" or "in range" data the user submits, but also on combinations of "incorrect" or "out of range" data, how the heck do -we do this?
One basic conceptual question is whether Data Validation is a +we do this?
+One basic conceptual question is whether Data Validation is a distinct process from Navigation Control or not. Initially we thought it was and that there should be a datamodel and set of procedures for checking user input, the output of which would pipe @@ -28,16 +28,21 @@ step we'll refer to here as Sequencing. (Note: we reviewed several alternatives in the archived prior discussions here.
+ So here is our current approach. We note that there are two scopes over which Sequencing needs to be handled:
- intra-item: checks pertaining to user responses to a single item
- inter-item : checks pertaining to user responses to more than one item; checks among multiple items will be built up pairwise
-So how might we implement this in our datamodel? Consider the + +
So how might we implement this in our datamodel? Consider the "sequencing" subsystem of the Assessment package:
-
Specific Entities
+ +
- Index: openacs-4/packages/assessment/www/doc/versioning.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/versioning.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/versioning.adp 20 Aug 2015 17:36:22 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/versioning.adp 25 Aug 2015 18:02:19 -0000 1.1.2.2 @@ -2,13 +2,13 @@+
Specific Entities
+
- Item-checks (as_item_checks) define 1..n ordered evaluations of a user's response to a single Item. These can occur either via client-side Javascript when the user moves focus from the Item, or @@ -106,4 +111,3 @@
{/doc/assessment {Assessment}} {Versioning} Versioning - - - Overview
This topic requires special mention because it is centrally +
Overview
+This topic requires special mention because it is centrally important to Assessment and one of the most radical departures from the current packages (in which "surveys" or "questionnaires" are all one-shot affairs that at best can be cloned but not readily -modified in a controlled fashion).
During its lifetime, an Assessment may undergo revisions in the +modified in a controlled fashion).
+During its lifetime, an Assessment may undergo revisions in the midst of data collection. These revisions may be minor (change of a label on an Item or adddition of a new Choice to an Item) or major (addition or deletion of an entire Section). Obviously in most @@ -17,51 +17,63 @@ the Assessment package must accommodate them. Clinical trial protocols change; teachers alter their exams from term to term. And still, there is a crucial need to be able to assemble and interpret -data collected across all these changes.
Another type of "revision" occurs when a component (an Item +data collected across all these changes.
+Another type of "revision" occurs when a component (an Item Choice, Item, Section, or the entire Assessment) needs to be translated into another language. Even if the semantics of the component are identical (and they should be or you need a better translator ;-), the Assessment package needs to handle this situation correctly: an admin user needs to be able to "assign" the right language version to a set of subjects, and the returned user -data need to be assembled into trans-language data sets.
Note that two orthogonal constructs are in play here:
+data need to be assembled into trans-language data sets. +
+Note that two orthogonal constructs are in play here:
+
- Many-many relationships: a given Section may be reused in many different Assessments (eg if it contains commonly-needed Items such as questions about demographic details)
- Multiple versions: that same Section may exist in different versions in those different Assessments (eg if different Assessment authors add or subtract an Item, change wording of an Item's label, etc). This includes different translations of semantically identical text.
-Approach
The Content Repository (CR) in OpenACS is designed to handle +
Approach
+The Content Repository (CR) in OpenACS is designed to handle these complex design issues, though it is still undergoing refinements and how best to use it is also still being discovered. -So the ideas here are still somewhat exploratory.
For each of the package components that need to be versioned +So the ideas here are still somewhat exploratory.
+For each of the package components that need to be versioned (certainly the core components as_assessments, as_sections, as_items, and as_item_choices; but also other components like as_policies), we extend the basic CR entities cr_items and cr_revisions. Thus we actually have, for instance, two tables for -Items:
+Items: +
+
- as_items (a cr_item) for whatever "immutable" attributes there are
- as_items_revs (a cr_revision) for all mutable attributes including translations
-This pattern of dual tables is used for all components that need +
This pattern of dual tables is used for all components that need to behave this way. When an admin user creates a new Item, a new row is inserted into the as_items and the as_items_revs table. Then when the same admin user (or another admin user) changes something -about the Item, a new as_items_revs row is inserted.
Now here is where things become tricky, though.. Any time a +about the Item, a new as_items_revs row is inserted.
+Now here is where things become tricky, though.. Any time a component is changed, there is a simultaneous implicit change to the entire hierarchy. Data collected after this change will be collected with a semantically different instrument. Whether the difference is large or small is immaterial; it is different, and Assessment must handle this. And the CR doesn't do this for us -automagically.
So what the package must do is version both the individual +automagically.
+So what the package must do is version both the individual entities and also all the relationships over which we join when we're assembling the entire Assessment (whether to send out to a requesting user, to stuff the database when the form comes back, or -to pull collected data into a report).
This doesn't involve merely creating triggers to insert new +to pull collected data into a report).
+This doesn't involve merely creating triggers to insert new mapping table rows that point to the new components. We also need to insert new revisions for all components higher up the hierarchy -than the component we've just revised. Thus:
+than the component we've just revised. Thus: +
+
- If we change the text displayed with a Section, then we need to insert a new as_section_revs and a new as_section_assessment_map row. But we also need to insert a new as_assessment_revs as well, @@ -70,30 +82,36 @@ Section, though we do need to insert new as_section_item_map rows.
- If we change the text of an Item Choice, then we need to insert new stuff all the way up the hierarchy.
-Another key issue, discussed in this +
Another key issue, discussed in this thread, involves the semantics of versioning. How big of a modification in some Assessment package entity needs to happen before that entity is now a "new item" instead of a "new version of an existing item"? If a typo in a single Item Choice is corrected, one can reasonably assume that is merely a new version. But if an Item of multiple choice options is given a new choice, is this Item -now a new one?
One possible way this could be defined would derive from the +now a new one?
+One possible way this could be defined would derive from the hierarchy model in the CR: cr_items -- but not cr_revisions -- can contain other entities; the parent_id column is only in cr_items. Thus if we want to add a fifth as_item_choice to an as_item (while preserving the state of the as_item that only had four as_item_choices), we need to insert a new as_item and not merely a -new as_item_rev for the existing as_item.
A final point concerns the mapping tables. The OpenACS framework +new as_item_rev for the existing as_item.
+A final point concerns the mapping tables. The OpenACS framework provides a variety of special-purpose mapping tables that are all proper acs_objects (member_rels, composition_rels, acs_rels, and the CR's own cr_rels). These provide additional control over permissioning but fundamentally are mapping tables. In the long run the benefit of using them is the ability of OpenACS 6, to auto construct code based on cr_item_types and relationships.
-Specific Versionable Entities
Within each subsystem of the Assessment package, the following +
+Specific Versionable Entities
+Within each subsystem of the Assessment package, the following entities will inherit from the CR. We list them here now, and once we've confirmed this selection, we'll move the information out to -each of the subsystems' pages.
+each of the subsystems' pages. +
- Index: openacs-4/packages/assessment/www/doc/asm_trigger_doc/bi01.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/asm_trigger_doc/bi01.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/asm_trigger_doc/bi01.adp 20 Aug 2015 17:38:01 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/asm_trigger_doc/bi01.adp 25 Aug 2015 18:02:19 -0000 1.1.2.2 @@ -2,30 +2,20 @@
- Core - Items:
- Items: as_items; as_items_revs
- Item Choices: as_item_choices; as_item_choices_revs
- Localized Items: as_item_localized; as_item_localized_revs
@@ -123,4 +141,3 @@{/doc/assessment {Assessment}} {Bibliography} Bibliography - - - ++ - + + \ No newline at end of file Index: openacs-4/packages/assessment/www/doc/asm_trigger_doc/bi02.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/asm_trigger_doc/bi02.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/asm_trigger_doc/bi02.adp 20 Aug 2015 17:38:01 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/asm_trigger_doc/bi02.adp 25 Aug 2015 18:02:19 -0000 1.1.2.2 @@ -2,28 +2,19 @@ {/doc/assessment {Assessment}} {Bibliography} Bibliography - - - ++ - + + \ No newline at end of file Index: openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch01.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch01.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch01.adp 20 Aug 2015 17:38:01 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch01.adp 25 Aug 2015 18:02:19 -0000 1.1.2.2 @@ -2,31 +2,22 @@ {/doc/assessment {Assessment}} {Chapter 1. Design} Chapter 1. Design - - - ++ - +-Table of Contents
+ \ No newline at end of file Index: openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch01s01.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch01s01.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch01s01.adp 20 Aug 2015 17:38:01 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch01s01.adp 25 Aug 2015 18:02:19 -0000 1.1.2.2 @@ -2,31 +2,22 @@ {/doc/assessment {Assessment}} {1. Data Model} 1. Data Model - - - ++ - +It was necessary to add several tables to support the trigger and action execution.
-+ \ No newline at end of file Index: openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02.adp 20 Aug 2015 17:38:02 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02.adp 25 Aug 2015 18:02:19 -0000 1.1.2.2 @@ -2,16 +2,11 @@ {/doc/assessment {Assessment}} {Chapter 2. User Manual} Chapter 2. User Manual - - - ++ - +Table of Contents
@@ -26,17 +21,12 @@
Here are some statements to create triggers to branch between sections or execute actions:
-+ \ No newline at end of file Index: openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s01.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s01.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s01.adp 20 Aug 2015 17:38:02 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s01.adp 25 Aug 2015 18:02:19 -0000 1.1.2.2 @@ -2,16 +2,12 @@ {/doc/assessment {Assessment}} {1. Manage Permissions} 1. Manage Permissions - - - ++ - +To create an assessment is necessary to have create permissions over the assessment instance. This permission can be inherit or can @@ -25,17 +21,12 @@ permissions can be set.
Also the user can search for another user to manage his permissions:
After clicking OK, the user will appear in the list an the permissions can be set properly.
-+ \ No newline at end of file Index: openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s02.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s02.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s02.adp 20 Aug 2015 17:38:02 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s02.adp 25 Aug 2015 18:02:19 -0000 1.1.2.2 @@ -2,16 +2,12 @@ {/doc/assessment {Assessment}} {2. Actions Administration} 2. Actions Administration - - - ++ - +To be able to administrate actions the user must have site wide admin privileges. To admin actions the user must follow the link @@ -35,17 +31,12 @@ administration page must be followed:
Before deleting an action, a confirm message will be displayed, the action will not be deleted if there is some reference to this action (i.e. a trigger that wil execute this action).
-+ \ No newline at end of file Index: openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s03.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s03.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s03.adp 20 Aug 2015 17:38:02 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s03.adp 25 Aug 2015 18:02:19 -0000 1.1.2.2 @@ -2,16 +2,12 @@ {/doc/assessment {Assessment}} {3. Trigger Definition} 3. Trigger Definition - - - ++ - +After the assessment is created, the triggers can be defined for questions with multiple choice responses.
There are two type of triggers:
Branch: This trigger will make that the secuence of sections in @@ -21,17 +17,12 @@ depending on the answer that the user gives to the question related to the trigger, when the assessment is being responded.
The link to create a trigger appears in the action bar of the items with multiple choice responses of the assessment.
-+ \ No newline at end of file Index: openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s04.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s04.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s04.adp 20 Aug 2015 17:38:02 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s04.adp 25 Aug 2015 18:02:19 -0000 1.1.2.2 @@ -2,16 +2,12 @@ {/doc/assessment {Assessment}} {4. Branch Triggers} 4. Branch Triggers - - - +- ++ - +To define a Branch Trigger, the field "Type" in the form must be checked as branch. Is necessary that at least one section is @@ -20,17 +16,12 @@ response the trigger will be activated, and the section secuence will change.
After the trigger is defined as branch, the section that will be displayed next must be chosen:
-+ \ No newline at end of file Index: openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s05.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s05.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s05.adp 20 Aug 2015 17:38:02 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s05.adp 25 Aug 2015 18:02:19 -0000 1.1.2.2 @@ -2,16 +2,12 @@ {/doc/assessment {Assessment}} {5. Action Triggers} 5. Action Triggers - - - ++ To define an Action Trigger, the field "Type" in the form must be checked as "Action".
The condition field shows the question and its possible anwers, @@ -33,17 +29,12 @@ sections.
At the end of the assessment and Manually: display all the questions defined in the assessment.
-+ \ No newline at end of file Index: openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s06.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s06.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s06.adp 20 Aug 2015 17:38:02 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s06.adp 25 Aug 2015 18:02:19 -0000 1.1.2.2 @@ -2,16 +2,12 @@ {/doc/assessment {Assessment}} {6. Trigger Administration} 6. Trigger Administration - - - ++ - +The trigger administration page can be reached from two different links, the link "Administer Triggers" in the action bar @@ -28,17 +24,12 @@ showing all the information related to it.
The link "Notify User" leads to a page a user can request notifications when this trigger is executed. It also allowst to search and register another users to the notifications.
-+ \ No newline at end of file Index: openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s07.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s07.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s07.adp 20 Aug 2015 17:38:03 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch02s07.adp 25 Aug 2015 18:02:20 -0000 1.1.2.2 @@ -2,16 +2,12 @@ {/doc/assessment {Assessment}} {7. Request Administration} 7. Request Administration - - - ++ - +The request Administration page can be reached following the link in the action bar for a site wide administrator or following @@ -25,17 +21,12 @@ click in the button "Approve", and also can send mail to several users that requested the action. Through this interface the notifications can also be managed.
-+ \ No newline at end of file Index: openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch03.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch03.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch03.adp 20 Aug 2015 17:38:03 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch03.adp 25 Aug 2015 18:02:20 -0000 1.1.2.2 @@ -2,16 +2,11 @@ {/doc/assessment {Assessment}} {Chapter 3. Registration Assessment} Chapter 3. Registration Assessment - - - ++ - +To be able to select an assessment that will be related to the registration process is necessary that the user has site wide admin @@ -25,17 +20,12 @@ process will be the same as always has been, if any other option is selected, the assessment will be diplayed when a user creates a new account.
-+ \ No newline at end of file Index: openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch04.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch04.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch04.adp 20 Aug 2015 17:38:03 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/asm_trigger_doc/ch04.adp 25 Aug 2015 18:02:20 -0000 1.1.2.2 @@ -2,14 +2,11 @@ {/doc/assessment {Assessment}} {Chapter 4. Authors} Chapter 4. Authors - - - ++ - +Viaro Networks (www.viaro.net)
-
- @@ -20,15 +17,11 @@
Anny Flores -- annyflores\@viaro.net
Development and Documentation
+ \ No newline at end of file Index: openacs-4/packages/assessment/www/doc/asm_trigger_doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/asm_trigger_doc/index.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/asm_trigger_doc/index.adp 20 Aug 2015 17:38:03 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/asm_trigger_doc/index.adp 25 Aug 2015 18:02:20 -0000 1.1.2.2 @@ -2,15 +2,11 @@ {/doc/assessment {Assessment}} {Triggers and Action Execution in Assessment} Triggers and Action Execution in Assessment - - - ++ +- +++ \ No newline at end of file Index: openacs-4/packages/assessment/www/doc/user_interface/assessment_creation.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/user_interface/assessment_creation.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/user_interface/assessment_creation.adp 20 Aug 2015 17:39:08 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/user_interface/assessment_creation.adp 25 Aug 2015 18:02:20 -0000 1.1.2.2 @@ -2,15 +2,14 @@ {/doc/assessment {Assessment}} {Assessment Creation} Assessment Creation - - When creating an assessment the administrator has a couple of fields to determine the look and feel of the assessment along with the option to view the responses. This is a list of attributes the administrator can edit when creating an assessment. The grouping is based on the UI and not on the datamodell. So you should follow -this with regards to the UI: +this with regards to the UI: +
+ + \ No newline at end of file Index: openacs-4/packages/assessment/www/doc/user_interface/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/user_interface/index.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/user_interface/index.adp 20 Aug 2015 17:39:08 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/user_interface/index.adp 25 Aug 2015 18:02:20 -0000 1.1.2.2 @@ -2,22 +2,28 @@- +
- Title: Title of the accessment
- Anonymous Accessment: boolean (yes/no). This shows whether the creator of the accessment will have the @@ -174,5 +173,6 @@ with a timestamp. This isn't relevant in educational testing, but it is an important feature to include for other settings, notably medical and financial ones.
-{/doc/assessment {Assessment}} {Appendix A: RFC for Assessment Specs} Appendix A: RFC for Assessment Specs - - - Introduction
In recent times the survey system has +Introduction
+In recent times the survey system has expanded beyond it's initial scope of providing a quick and easy solution to conduct surveys. Due to it's flexibility it has already expanded in the area of storing user information and provide a tool -for feedback for quality assurance.On the other hand the need for dotLRN has +for feedback for quality assurance. +
On the other hand the need for dotLRN has risen to provide an assessment solutions that allows (automated) tests as well with the possibility to score the test results and -store them in an easy retrievable way.
Last but not least a new demand has risen +store them in an easy retrievable way.
+Last but not least a new demand has risen for the possibility to give and store ratings on objects within the -system as part of a knowledge management solution.
The documents on these page will provide a +system as part of a knowledge management solution.
+The documents on these page will provide a solution that is flexible to meet ababove needs but still be -focused enought to apply for special clients demands.
Assessments
The current survey system will build the +focused enought to apply for special clients demands. +Assessments
+The current survey system will build the basis for a new assessment package and will consist of various -areas:Question Catalogue
The question catalogue stores all the +areas: +Question Catalogue
+The question catalogue stores all the questions of the assesment package. It is a pool where all the questions from all assessments are stored in. This creates the opportunity to make the questions reusable, allowing for statistics @@ -27,91 +33,111 @@ not store the results within the scope of the assessment package but in other database tables (e.g. the name of the user) or trigger some other events (e.g. send email to the email address filled out -by the respondee). A detailed description can be found here.Assessment creation
An assessment is either a survey or a test. +by the respondee). A detailed description can be found here. +Assessment creation
+An assessment is either a survey or a test. The functionality for both is nearly identical though a test needs additional work to allow for automated grading. A detailed description of the options given to the creator of an assessment can be found here. -Each assessment consists of various + +
Each assessment consists of various sections, that allow for the split up of the assessment (so it will be displayed to the respondee on multiple pages) and give the possibility for branching depending on previous answers of the respondee. Questions are always added into the question database first, then added to a specific section and thus made available to the assessment. A detailed description of the Sections can be found -here.
Tests
Tests are a special kind of assessment in +here. +Tests
+Tests are a special kind of assessment in that they allow for automatic processing of the answers and storage of the result in the grading system. They have a couple of additional settings as well as the possibility to get an overview of the evaluation (what have the respondees answered, how have they done in total (points)). A description for this can be found -here.The backend for the test processing, that +here. +
The backend for the test processing, that enables the automatic tests is described in a seperate document as it will be parsed while the respondee answers the test, not manually. In addition this document describes how the grades are calculated (automatically or manually) for each question. The result is beeing stored in the -grading package.
Scoring/Grading
The grading package will be designed first of +grading package. +Scoring/Grading
+The grading package will be designed first of all to all the storing of test results. In addition to this, it will provide functionality to other packages to allow rating of their contents (one example of this would be Lars Rating package, that would be used as a basis for this). In general it should provide a very flexible way of adding scores into the system, either automatically (as described above) or manually (e.g. this -student did a good oral exam).In addition to the possiblity to enter +student did a good oral exam). +
In addition to the possiblity to enter scores/rates, the grading package allows for automatic aggregation of scores. This holds especially true for tests and classes. A test result will depend on the result of all the answers (aggregated). A class result will depend on the result of all the tests a respondee did in addition to any manual grades the professor can come up with. Providing a clean UI for this is going to be the -challange.
Furthermore the grading package offers to +challange.
+Furthermore the grading package offers to transfer scores (which are stored as integer values) into a grade (e.g. the american A-F scheme, or the German 1-6). This is where it gets the name from I'd say ;). Grading schemes are flexible and can be created on the fly. This allows us to support any grading scheme across the world's universities. In addition in the area of Knowledge Management, grades could be transfered into incentive points, that can be reused to reward employees for good work done -(where they got good ratings for).
Last but not least, maybe embeded with the +(where they got good ratings for).
+Last but not least, maybe embeded with the workflow system, is the possibility to execute actions based on the grade. An example would be the adding of the student to the advanced class if his grade or score reaches a certain level. Alternatively this looks like a good thing for the curriculum -module to achieve.
User Experience
So far we have only talked about the +module to achieve. +User Experience
+So far we have only talked about the administrators point of view. A respondee will be directed to an assessment from various possible entry points. Depending on the settings for the assessment the respondee will be presented with the assessment that he is allowed to answer. Though a lot of it is redundant, a special page has been created to describe this. For the implementation though there might be additional things depending on the specifications of the various -administrator settings.Use Cases
The most obvious use case would be a class in +administrator settings. +Use Cases
+The most obvious use case would be a class in a school or university, that offers automated tests to the students and wants to have them graded automatically. The description of the -assessment system has been written mainly with this in mind.Additionally you can use the assessment +assessment system has been written mainly with this in mind. +
Additionally you can use the assessment system to collect user information. When signing up to a site the user could be asked to fill out an assessment where part of the questions will be stored in the acs_users table, some other questions in other tables and the rest in the accessment package. This way a quick view can be given about the user (aggregating user information in a flexible way). Best explanation would be to treat the /pvt/home page as a collection of assessment data and the -"change basic information" as one assessment among many.
With a little bit of tweaking and the +"change basic information" as one assessment among many.
+With a little bit of tweaking and the possiblity to add instant gratification, aka aggregated result display, it could include the poll package and make it -redundant.
Last but not least with the ability to +redundant.
+Last but not least with the ability to display questions in a multi dimensional way to the user, the assessment system is usefull for quality assurance (how important is this feature / how good do you think we implemented it). And as you might have guessed, for anything the current survey module has -been used for as well (e.g. plain and simple surveys).
The grading system on it's own would be +been used for as well (e.g. plain and simple surveys).
+The grading system on it's own would be usefull for the OpenACS community as it would allow the handing out of "zorkmints" along with any benefits the collection of mints gives to the users. As mentioned earlier, this is also very important in a Knowledge Management environment, where you want to -give rated feedback to users.
+ - Index: openacs-4/packages/assessment/www/doc/user_interface/item_creation.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/user_interface/item_creation.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/user_interface/item_creation.adp 20 Aug 2015 17:39:09 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/user_interface/item_creation.adp 25 Aug 2015 18:02:20 -0000 1.1.2.2 @@ -2,20 +2,21 @@+give rated feedback to users.
++
-{/doc/assessment {Assessment}} {Question Catalogue} Question Catalogue - - -Question Catalogue: Summary: +The question catalogue is a central part +Question Catalogue: Summary:
The question catalogue is a central part of the assessment system. It deals with the storing of the various questions that can be used in a survey. You are able to add/edit/delete a question of a certain type to a certain scope. Furthermore it allows you to search and browse for questions for inclusion in your assesment as well as import and export multiple questions using various formats. This concept is new to survey 0.1d and changes the design of the survey module considerably. No -mockups available.
+mockups available.
+Spec:
-All questions have some common ground.+All questions have some common ground. +
+For each of the various question types, there will be a seperate input form instead of the currently used method. A user selects a question type to add and is then redirected to the -question type add form.For each of the various question types, there +
- Questions must be scopeable, scope should be:
@@ -33,10 +34,12 @@ easily be found again.
- Questions have to be versionable. This allows a survey to use the older version of a question, if the question is changed.
-+question type add form. +
Concerning permissions here is the current -thinking:Only site wide admins will get to see the -following question types:
- True for all Question types
-
The following fields are true for every question type:@@ -211,8 +214,10 @@ setup (if all questions in a section have the same answers they would be shown in a matrix). One could think about making this a special question type on it's own.
+Only site wide admins will get to see the +following question types: +
- +
-
- Database question:
The answer to this question will be stored in the database. The question has the following additional fields:@@ -223,8 +228,10 @@ column of the table that matches the user_id of the respondee.
+
+Concerning permissions here is the current +thinking: +There needs to be an option to search the -question catalogue:
- A question can be changed only by the creator or any person that the creator authorizes. To keep it simple for the moment, a person that is authorized by the creator @@ -234,8 +241,10 @@ stick with their revision of the question.
- If an upgrade happens we have to make sure that the survey gets reevaluated. Unsure about the exact procedure here.
-+
+There needs to be an option to search the +question catalogue: +-Operations on questions:
- Search term: short_text. What shall be searched for
- Search type: select {exact, all, either}. Search for the exact term, for all terms or for one of the terms @@ -255,7 +264,9 @@ WebCT or IMS format.
+
+Operations on questions: +For the future we'd like to see a more + +For the future we'd like to see a more sophisticated way to include images in questions. Currently this can be done using HTML linking, but a media database would be considerably more helpful and could be reused for the CMS as -well.
- View. View the question in more detail (all settings along with a preview of the question)
- Edit. Edit the current question. On @@ -275,18 +286,23 @@ answers. Currently this can be done using HTML linking. A more sophisticated system which links to a media database is thinkable, once the media database is ready.
-Calculation and Database Questions
+well. +
+Calculation and Database Questions
+ I'm not clear from your description what these are. If by Calculation questions you mean questions that produce some calculated result from the user's raw response, then IMHO this is an important type of question to support now and not defer. This is the main type of question we use in quality-of-life measures (see demo -here). These are questions scored by the Likert scale +here +). These are questions scored by the Likert scale algorithm. If there are five potential responses (1,2,3,4, and 5) for a question, and the user choose "1" then the "score" is calculated as 0; if "5" then 100; if "3" then 50, and so on -- a @@ -297,7 +313,9 @@ answer that needs to be stored during question creation? Then when the teacher is reviewing the student's response, she can inspect the student's response against the stored answer and determine what -degree of correctness to assign the response?-- Stan +degree of correctness to assign the response?
+-- Stan Kaufman on November 09, 2003 06:29 PM (view -details)
- +details) + + \ No newline at end of file Index: openacs-4/packages/assessment/www/doc/user_interface/section_creation.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/user_interface/section_creation.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/user_interface/section_creation.adp 20 Aug 2015 17:39:09 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/user_interface/section_creation.adp 25 Aug 2015 18:02:20 -0000 1.1.2.2 @@ -2,8 +2,6 @@{/doc/assessment {Assessment}} {Sections} Sections - - Section page. This page is for editing information about a section and adding questions to it. It contains a couple of subpages. Datamodell can be found here.
@@ -12,7 +10,8 @@ the following pages.
The section edit page contains the following Items:
-+ +
++ The branch conditions page allows the conditions to be added under which this section will be called (branch conditions). This is still work in progress and will not be developed in the first -phase.
- Title: Title of the section
- Description: text used for identification and selection in admin pages, not for end-user pages
- Instructions: text displayed on user pages describing the user how to fill out the section.
- @@ -31,10 +30,12 @@ questions.
+phase.
+-
- Sequencing Information
@@ -47,7 +48,8 @@ boolean. Is it mandatory that all conditions have been met or is one condition enough (for not displaying this section)+
+
- Branch by question. This kind of branch depends on previous answers. A @@ -89,9 +91,12 @@ is imagineable that a combination of both methods makes sense, so we should take this into account when creating the UI.
-
+
+ Below this information we have a paragraph where all questions are -displayed with the options to+displayed with the options to
+ - Index: openacs-4/packages/assessment/www/doc/user_interface/tests.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/user_interface/tests.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/user_interface/tests.adp 20 Aug 2015 17:39:09 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/user_interface/tests.adp 25 Aug 2015 18:02:20 -0000 1.1.2.2 @@ -2,12 +2,11 @@
++
- Edit question
- Search and add question(s) from question database: Link to the search page which allows to search for questions that can be added @@ -105,7 +110,7 @@ section. It will be displayed in any case, regardless of randomizing.
- Fixed Position: select (1,2..., buttom). Position the question has to be displayed, regardless of randomizing.
-{/doc/assessment {Assessment}} {Tests} Tests - - A test is a special kind of accessment that allows the respondee's answers to be rated immediatly. Unless otherwise stated, all pages -described are admin viewable only. +described are admin viewable only. +
+Test processing happens in +a multiple stage process. +Test processing happens in -a multiple stage process.
- Settings
-
- Assessment: a selectbox containing all @@ -64,8 +63,10 @@ test, reports and summary are given.
+
Autograding is different for the types of + +Autograding is different for the types of questions the test has. For future versions it should be possible to easily add other types of information that will be autograded. -All autograding follow this scheme:
- The system evaluates the test as good as it can.
- The results of this auto-grading are displayed in the evaluation table for the admin (see test @@ -74,10 +75,12 @@ This is mandatory for open questions for the test to be completly graded.
- The result of the human grading overwrites the auto grading in the scoring system.
-+All autograding follow this scheme:
+Autograding is different for each type of -question.
- The answer is taken from the respondee response
- It is compared with the correct answer
- A percentage value is @@ -88,8 +91,10 @@ system.
- Once finished with all the questions, the result for the test is computed and stored with a link to the response in the scoring system.
-+ +Autograding is different for each type of +question. +
+Human grading will display all the questions and answers of response along with the possibility to reevalutate the points and give comments. The header will display the following -information:Human grading will display all the questions +
- Multiple Choice
-
- All or nothing. In this scenario it will @@ -135,10 +140,12 @@ negative percentage can be the result.
+information: +
+ + - Index: openacs-4/packages/assessment/www/doc/user_interface/user_experience.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/user_interface/user_experience.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/assessment/www/doc/user_interface/user_experience.adp 20 Aug 2015 17:39:09 -0000 1.1.2.1 +++ openacs-4/packages/assessment/www/doc/user_interface/user_experience.adp 25 Aug 2015 18:02:20 -0000 1.1.2.2 @@ -2,12 +2,11 @@For each question the following will be -displayed
- Title of the test
- Name of the respondee
- Number of the try / total number of tries
- Status of the try (finished, unfinished, autograded, human graded (by whom))
- Start and Endtime for this @@ -147,8 +154,10 @@ response.
- Comment: richtext. Comment for the number of points given. Prefilled with the current version of the comment.
-+
+For each question the following will be +displayed +-
- Question Title.
- Maximum number of points for this question.
- Question.
- New Points: Integer. Prefilled with the current value for the response. This is the possibility for staff @@ -177,7 +186,7 @@ interesting to display regexps here :-).
{/doc/assessment {Assessment}} {User Experience} User Experience - - User experience describes the various steps the USER sees and what he can do when taking an assessment. When answering a section a couple -of things happen: ++of things happen:
Depending on the settings, the display of the -assessment will vary:
- A permission check will be made to determine whether the user is allowed to take the @@ -20,8 +19,10 @@
- Starttime of the response will be logged
- First section will be delivered to the user for anwering.
-+
+Depending on the settings, the display of the +assessment will vary: +The processing has to take some additional -notes into consideration:
- If all answers have to be submited seperatly, a submit button will be shown next to each answer. If the user hits the submit button next to the question the answer @@ -46,8 +47,10 @@ ad_form check) for a question is true, check the answer if it is valid, otherwise notify the user that it is not and do not store the result.
-+
+The processing has to take some additional +notes into consideration: +Once the assessment has been finished
- Branching does not always depend on an answer but may also depend on the result within a section (branch by disctractor, median)
- questions within a section can be @@ -57,7 +60,9 @@ randomizing element has to be the same for each response_id (the user shall not have the option to see different questions just by hitting reload).
-+
+Once the assessment has been finished +An administrator can take the survey in + +An administrator can take the survey in various modes which he can select before the first section will be -displayed.
- Display optional electronic signature file upload with an "I certify this test and state it is mine" checkbox. This will be stored in addition to the test.
- Notifications shall be send to the admin, @@ -69,14 +74,17 @@ display this along with the 90%).
- Display a link with the possibility to show all the questions and answers for printout.
- Store the endtime with the response.
-+displayed.
+- + + + \ No newline at end of file Index: openacs-4/packages/attachments/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/attachments/www/doc/index.adp,v diff -u -N -r1.1.2.3 -r1.1.2.4 --- openacs-4/packages/attachments/www/doc/index.adp 21 Aug 2015 10:28:47 -0000 1.1.2.3 +++ openacs-4/packages/attachments/www/doc/index.adp 25 Aug 2015 18:02:20 -0000 1.1.2.4 @@ -2,9 +2,8 @@
- Normal mode: The adminsitrator is treated as a normal respondee, the response will be stored in the system.
- Test mode: The administrator sees the survey as a normal respondee, the response will not be stored in the system.
- Optional: Display correct answers when taking the assessment.
-{/doc/attachments {Attachments}} {} - - - Contents
+
- +
Contents
+
- 1 Attachments
-
- 1.1 Basics
@@ -24,62 +23,87 @@
1 Attachments
-1.1 Basics
+
+1 Attachments
++1.1 Basics
+1.1.1 What does -attachments do?
+attachments do? +
attachments is a service package that allows you to attach one or more file-storage files to any acs_object. attachments is mounted below a package that uses it, and the application provides links into the attachments package's -UI.
+UI. +
1.1.2 At a high level, -how does attachments work?
Before you can use the attachments package, each instance of +how does attachments work? +
Before you can use the attachments package, each instance of your package must be mapped to a file-storage root -folder.
The root folder is a "super folder" for all the files in that +folder.
+The root folder is a "super folder" for all the files in that specific instance of file-storage, and it is created automatically -when the file-storage package is instanciated.
When a user wants to make an attachment to an object in your +when the file-storage package is instanciated.
+When a user wants to make an attachment to an object in your package, she is shown the contents of the file-storage root folder mapped to your package instance. The user is also given the option -to upload a new file into file-storage to attach.
-1.2 Using attachments
+to upload a new file into file-storage to attach. +
+1.2 Using attachments
+1.2.1 Mount attachments -under your package
The first step is to mount the attachments package under +under your package +
The first step is to mount the attachments package under your package. In the site-map, you should create a new -site-node (sub-folder) under your package called "attach".
"attach" is the standard URL, however URL this can be changed on +site-node (sub-folder) under your package called "attach".
+"attach" is the standard URL, however URL this can be changed on a site-wide basis by changing the "RelativeUrl" parameter of any of the attachments packages (this works since there's only one instance of attachments in the entire system. The same -instance is just re-mounted)
+instance is just re-mounted) +
1.2.2 Map an -file-storage root folder to your package instance
First, you must select a file-storage instance that will provide +file-storage root folder to your package instance +
First, you must select a file-storage instance that will provide the files you can attach. If you do not already have an instance of file-storage that you want to use for your package instance, you -must create one using the site-map.
Once you have a file-storage instance you wish to use, you must +must create one using the site-map.
+Once you have a file-storage instance you wish to use, you must map the root folder of that file-storage instance with the -package_id of the instance of your package.
Two utility procs to help you do this:
+package_id of the instance of your package.
+Two utility procs to help you do this:
+fs::get_root_folder and attachments::map_root_folder -
+ +
+1.2.3 Attaching files to -your objects
+your objects
1.2.3.1 Have your -package check if attachments is mounted properly
Most likely, you want your package to work even if the +package check if attachments is mounted properly +
Most likely, you want your package to work even if the attachments package is not installed on the system or if attachments is not properly mounted. To do this, add the following proc to your package's API and wrap all calls to the attachments -package with it:
++package with it: +ad_proc -private attachments_enabled_p {} { set package_id [site_node_apm_integration::child_package_exists_p \ -package_key attachments ] } -+
1.2.3.2 Get the -attachment Url
When you want to set up the link that the user can click on to +attachment Url +
When you want to set up the link that the user can click on to attach something to an object, use the attachments::add_attachment_url proc, which will return the correct -Url into the attachments package mounted under your package.
++Url into the attachments package mounted under your package. +if {$attachments_enabled_p} { if {$attach_p} { set redirect_url [attachments::add_attachment_url \ @@ -88,9 +112,13 @@ -pretty_name "$subject"] } } -forums redirects the user to the redirect_url, if the user chose -to add an attachment to their posting.
+
forums redirects the user to the redirect_url, if the user chose +to add an attachment to their posting.
+1.2.4 Viewing attached -files
You can use the "attachments::get_attachments" proc to see the -list of attachments to a given object.
Release Notes
Please file bugs in the Bug Tracker.
- +files +You can use the "attachments::get_attachments" proc to see the +list of attachments to a given object.
+Release Notes
+Please file bugs in the Bug Tracker.
Index: openacs-4/packages/calendar/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/calendar/www/doc/index.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/calendar/www/doc/index.adp 20 Aug 2015 17:35:00 -0000 1.1.2.1 +++ openacs-4/packages/calendar/www/doc/index.adp 25 Aug 2015 18:02:20 -0000 1.1.2.2 @@ -2,39 +2,60 @@{/doc/calendar {Calendar}} {OpenACS Calendar package} OpenACS Calendar package - - - OpenACS Calendar package
OpenACS documentationThe OpenACS calendar package is a web-based calendar package. In +
OpenACS Calendar package
+OpenACS documentation +The OpenACS calendar package is a web-based calendar package. In its current form it provides a UI for storing events that have a time or that last a day, and it offers a list view, a day, week, -and month view.
The project plan for calendar can be found at http://openacs.org/projects/openacs/packages/calendar/. +and month view.
+The project plan for calendar can be found at http://openacs.org/projects/openacs/packages/calendar/. The maintainer of this package is Dirk Gomez -
The Data Model
Permissions
Calendar uses a lot of custom permissions. Most of them are +
+The Data Model
+Permissions
+Calendar uses a lot of custom permissions. Most of them are unused and will be removed eventually. It will then use a Unix-like -set of read, write, create, admin permissions.
Calendars
A calendar has a name and an owner and belongs to a package, it +set of read, write, create, admin permissions.
+Calendars
+A calendar has a name and an owner and belongs to a package, it also is an acs_object. This goes into the table calendars. A calendar is created via the usual constructor - a "new" function" - -and destroyed via the usual destructor - a "delete" function.
The calendar package currently uses its own little category +and destroyed via the usual destructor - a "delete" function.
+The calendar package currently uses its own little category system: calendar item types can be created per package, they are -stored in the table cal_item_types
The table cal_party_prefs allows storing customization +stored in the table cal_item_types
+The table cal_party_prefs allows storing customization information per calendar and per user. It is completely unused and I couldn't find any traces of it ever having been used. A similar table will be used in a future version of calendar to store user -options though.
Code Contributors
+options though. +
+Code Contributors
+
- Ben Adida - partial refactoring of the original OpenACS 4.X calendar, integration into .LRN
- Gary Jin and W. Scott Meeks from late ArsDigita - original OpenACS 4.X calendar
- Lars Pind and Paul Doerwald - pair programming during bug bashes
- Raad Al-Rawi from Cambridge University for calendar.css and a lot of the layout.
- Lilian Tong and Charles Mok for the original PostgreSQL port
-Change Log
HEAD
+
+Change Log
+HEAD
+
- Notifications
- Removed unused or duplicated code and database queries.
-OpenACS 5.0
+
+OpenACS 5.0
+
- Separation of html and tcl, noquote
- Proper use of OpenACS permissioning
- A lot of unused code was removed.
-Test Cases
I am planning to use acs-automated-tests for subsequent releases +
Test Cases
+I am planning to use acs-automated-tests for subsequent releases of calendar, I am collecting the test -cases in this document.
Old Docs
Dirk -Gomez -Last modified: Thu Jan 22 23:51:17 CET 2004 - +cases in this document. +Old Docs
+ +
+Dirk +Gomez + +Last modified: Thu Jan 22 23:51:17 CET 2004 \ No newline at end of file Index: openacs-4/packages/calendar/www/doc/requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/calendar/www/doc/requirements.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/calendar/www/doc/requirements.adp 20 Aug 2015 17:35:00 -0000 1.1.2.1 +++ openacs-4/packages/calendar/www/doc/requirements.adp 25 Aug 2015 18:02:20 -0000 1.1.2.2 @@ -2,16 +2,19 @@{/doc/calendar {Calendar}} {Calendar Package Requirements} Calendar Package Requirements - - Calendar Package Requirements
-by Gary Jin and W. Scott MeeksI. Introduction
+ +by Gary Jin + and W. Scott Meeks +I. Introduction
+ A calendar is an aggregate of events which fall within a given time interval, e.g., on a particular day, week, or month. The ArsDigita Calendar application provides users with a tool which allows them to add, view, edit and organize these events at both the personal and party/group levels.II. Vision Statement
+ The ArsDigita Calendar application is a Web based calendar system that can be accessed through any browser. The application allows people to keep track of events as they normally would on a paper @@ -30,10 +33,14 @@ particular ACS parties where each party member can see events associated with that particular party. Events from the various parties of which one is a member can also be shown on a party -member's personal calendar.This package could be used for any application where event +member's personal calendar.
+This package could be used for any application where event tracking is important. This would include many business, -educational, club, and other community scenarios.
III. System/Application Overview
-In our system, a party-specific event is an event associated +educational, club, and other community scenarios. +III. System/Application Overview
+ +In our system, a 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 @@ -48,30 +55,42 @@ which they do not wish to have appear on their calendars. Since in our system, groups are parties and parties can have calendars, this account of a user's calendar generalizes to cover a party's -calendar.The Calendar Package is built on top of the ACS Event service -package and performs the following three high-level functions:
+calendar. +
+Event Management + covers those aspects of the application which pertain to events, such as adding, editing, viewing, deleting -events, and setting up recurring events. An event is defined -as an activity associated with one or more time intervals. +events, and setting up recurring events. An event + is defined +as an activity + associated with one or more time intervals. For instance, "participating in an ACS bootcamp" is an activity, but "participating in the ACS bootcamp during the upcoming week" is an event. Therefore, the Event Management portion would also needs to deal with scheduling issues associated with adding a temporal -aspect to activities . +aspect to activities + .The Calendar Package is built on top of the ACS Event service +package and performs the following three high-level functions:
+Event Management covers those aspects of the application +
- Event Management
- Calendar Views
- Navigation
-Calendar Views covers those aspects of the application which pertain to the display of calendar events for a particular -span of time.
+span of time.
+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
+currently being displayed. +IV. Use-cases and User-scenarios
+ There are three main classes of users for the Calendar:-The individual is primarily interested in having a personal + +The individual + is primarily interested in having a personal Web based calendar. The calendar needs to support the manipulation of basic calendar event components, among these: times, titles, and possibly descriptions. Example: Irwin Individual wants to be able @@ -93,7 +112,8 @@ functionality, the calendars for groups and parties would 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.
- Individuals
- Groups and Parties
- Administrators
+administrator must be assigned to handle event managment.
+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 @@ -104,282 +124,419 @@ bootcamps is scheduled to take place this month is incorrect. He has the permission to change it. He also can grant Jane Bootcamp write permission on that particular event, so that Jane can make -changes on her own.
V. Related Links
+changes on her own. +
+V. Related Links
+
- Design Document
- System Overview
- MIT's 6.916 course calendar
- vCalendar/iCalendar proposed standards
- Acceptance Tests
- Yahoo Calendar
- Excite Planner
-VI.A Requirements: Private Calendar
10 Private Calendar10.0 User Interface
+
VI.A Requirements: Private Calendar
+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.
+private, public or party-specific events are to be displayed.
+10.0.20 The calendar should support navigation to view -different dates in a simple manner.
+different dates in a simple manner.
+10.0.30 Links to different calendar functions should be -clear and obvious.
+clear and obvious.
+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.
+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 noticeable location
10.10.10 List View
+clear and noticeable location
+10.10.10 List View
+10.10.10.10 The calendar should support a view showing -selected items in a tabular list format.
+selected items in a tabular list format.
+10.10.10.20 Columns should include date, time, and other -relevant information.
-10.10.10.30 The columns should be sortable.
+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 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
+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 events for a particular day.
+all the events for a particular day.
+10.10.20.20 This view should show the events arranged -chronologically with a time guide along one side.
+chronologically with a time guide along one side.
+10.10.20.30 The range of the time guide should be -user-specifiable.
+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.
+which fall selected calendar events are shown.
+10.10.20.50 Overlapping events should be displayed in an -easy to understand fashion.
+easy to understand fashion.
+10.10.20.60 There should be a simple mechanism for adding -events which start at a particular hour.
+events which start at a particular hour.
+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
+include a slot for these items.
+10.10.30 Week View
+10.10.30.10 The calendar should support a view showing -all the events for a particular week.
+all the events for a particular week.
+10.10.30.20 The events for a particular day should be -grouped together.
+grouped together.
+10.10.30.30 There should be a simple mechanism for adding -an event for a particular day.
+an event for a particular day.
+10.10.30.40 The currently selected day should be -highlighted or otherwise clearly indicated to the user.
+highlighted or otherwise clearly indicated to the user.
+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
+previous week from this particular view.
+10.10.40 Month View
+10.10.40.10 The calendar should support a view showing -all the items for a particular month.
+all the items for a particular month.
+10.10.40.20 The events for a particular day should be -grouped together.
+grouped together.
+10.10.40.30 There should be a simple mechanism for adding -an event for a particular day.
+an event for a particular day.
+10.10.40.40 The currently selected day should be -indicated.
+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.
+item.
+10.10.40.60 There should some way to move to the next and -previous week from this particular view.
+previous week from this particular 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
+day view for that day.
+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.
+for the days displayed.
+10.10.50.20 For each month, there should be a link to the -month view of that month.
+month view of that month.
+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
+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 together related navigation links. This should be -similar to the widget provided by Yahoo Calendar and Excite Planner.
+similar to the widget provided by Yahoo Calendar and Excite Planner.
+10.20.10.20 Navigation to a different date should -maintain the same view.
+maintain the same view.
+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.
+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 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.
+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 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.
+some manner.
+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.
+that employed by Yahoo Calendar.
+10.20.10.70 The widget should clearly display today's -date along with some mechanism for navigating to that date.
+date along with some mechanism for navigating to that date.
+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.
+at a time.
+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
+time.
+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.
+being viewed.
+10.20.20.20 Selecting a day in week, month, or year view -should take you to the day view for the that day.
+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 the month view for that month.
10.30 Adding Events
+you to the month view for that month.
+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.
+and an indicator as to whether or not this event recurs.
+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.
+viewed date and the present time.
+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.
+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 form with the date defaulting to the currently viewed date -and the 'no start time' indicator set.
+and the 'no start time' indicator set.
+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.
+hour later.
+10.30.60 The week view should have a link for each day -for adding an item.
+for adding an item.
+10.30.70 The month view should have a link for each day -for adding an item.
+for adding an item.
+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
+days and different views.
+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
+attachment, and delete.
+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 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.
+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 interval, the number of intervals between recurrences, and any -specific information for the selected type of interval.
10.70 Editing Recurring Events
+specific information for the selected type of interval.
+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
+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 an attachment to that item. Selecting that link should bring up -a form to add attachments of various types.
+a form to add attachments of various types.
+10.80.20 The form should include a field for the title of -the attachment.
+the attachment.
+10.80.30 One type of admissible attachment supported should be an uploaded file. This type should be handled in the -standard ACS manner.
+standard ACS manner.
+10.80.40 One type of admissible attachment should be a -URL.
+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.
+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 should return to the view of the item which should have a -list of attachments including the attachment just added.
+list of attachments including the attachment just added.
+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.
+attachment, and a link to edit it.
+10.80.80 For a file attachment, the content link should -return the content of the file.
+return the content of the file.
+10.80.90 For a URL attachment, the content link should -navigate to the URL.
+navigate to the URL.
+10.80.100 For a text attachment, the content link should -display the entered text.
+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 of the attachment.
10.90 Inviting other groups to view Events
+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 of the event to invite other groups, individual or parties to -add this event to their personal calendars.
10.100 Deleting events
+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 that item.
+delete that item.
+10.100.20 Selecting the delete link should bring up a -confirmation dialog.
+confirmation dialog.
+10.100.30 If the item is not recurring, then the choice -button will simply be labeled 'OK'.
+button will simply be labeled 'OK'.
+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.
+the current instance only or all occurrences.
+10.100.50 Selecting 'Cancel' should return to the item -view.
+view.
+10.100.60 Selecting 'OK' should delete the item in -question.
+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.
+deleted as well.
+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+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 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.
+belongs.
+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.
+that party appear on the personal calendar.
+20.40 On a user's calendar, party-specific events should -indicate to which party they are specific.
+indicate to which party they are specific.
+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+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 chooses to add an event, the choice of which party to -associate with that event is given.
+associate with that event is given.
+30.20 There should also be a page where permissions of read, write, approve, and delete can be given to different -parties
+parties
+30.30 There should be a link to the admin page for the -group.
+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 Administration40.10 Calendar User Privilege Administration
+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 can be set for different parties
+permissions can be set for different parties
+40.10.20 Cal Admin can also add new user -party/groups/person to the entire calendar
+party/groups/person to the entire calendar
+40.10.30 Cal Admin can also add new user -party/groups/person to indivdual calendar items
40.20 Calendar Items Administration
+party/groups/person to indivdual calendar items
+40.20 Calendar Items Administration
+40.20.10 Provides the funcationality to delete, add, edit -any item on the calendar
+any item on the calendar
+40.20.20 Provides the funcatinality to allow Calendar -Administrator to change the permissions on each calendar item.
+Administrator to change the permissions on each calendar item.
+40.20.20 Provides the funcatinality to allow Calendar Administrator to change the default permissions of the entire calendar
-VI.E Requirements: API
50 API50.10 Calendar Events Manipulation
+
+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. 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
+in the database.
+50.20 Calendar Views
+50.20.10 Provide a function to generate the HTML for the -list view.
+list view.
+50.20.20 Provide a function to generate the HTML for the -day view.
+day view.
+50.20.30 Provide a function to generate the HTML for the -week view.
+week view.
+50.20.40 Provide a function to generate the HTML for the -month view.
+month view.
+50.20.50 Provide a function to generate the HTML for the -year view.
+year view.
+50.20.60 Provide a function to generate the HTML for the -calendar navigation.
+calendar navigation.
+50.20.70 Provide a function to generate the HTML for the -complete calendar.
VII. Revision History
+complete calendar. +
+VII. Revision History
+
+
Document Revision # Action Taken, Notes When? By Whom? @@ -399,8 +556,9 @@ - 0.7 Further Revisions 2000/12/06 Joshua Finkler and Gary Jin
+
+ gjin\@arsdigita.com and smeeks\@arsdigita.com - Index: openacs-4/packages/calendar/www/doc/test-cases.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/calendar/www/doc/test-cases.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/calendar/www/doc/test-cases.adp 20 Aug 2015 17:35:00 -0000 1.1.2.1 +++ openacs-4/packages/calendar/www/doc/test-cases.adp 25 Aug 2015 18:02:20 -0000 1.1.2.2 @@ -2,9 +2,10 @@{/doc/calendar {Calendar}} {OpenACS Calendar package - test cases} OpenACS Calendar package - test cases - - - OpenACS Calendar package - test cases
- Create an item that starts at 00:00
Dirk -Gomez -Last modified: Thu Jan 22 23:51:17 CET 2004 - +OpenACS Calendar package - test cases
++
- Create an item that starts at 00:00
+Dirk +Gomez + +Last modified: Thu Jan 22 23:51:17 CET 2004 \ No newline at end of file Index: openacs-4/packages/categories/www/doc/design.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/categories/www/doc/design.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/categories/www/doc/design.adp 20 Aug 2015 17:32:41 -0000 1.1.2.1 +++ openacs-4/packages/categories/www/doc/design.adp 25 Aug 2015 18:02:21 -0000 1.1.2.2 @@ -2,10 +2,12 @@{/doc/categories {Categories}} {Categories} Categories + Categories
+Object Names and IdHandler Service Contract +Functionality overview
- -Categories
Object Names and IdHandler Service ContractFunctionality overview
Categories are organized in separate category trees.
+ When a package admin clicks on an Administer Categories link, they are presented with a page that shows the following items:@@ -14,10 +16,13 @@ are just the trees that the admin has the 'category_read' permission on
+ Creating a new tree involves entering tree name and description. The name must be unique among all the trees.- link to create and map a new category tree
+ Upon creation of a tree, the admin is granted the 'category_read' and 'category_write' permisssions.
+ Normally, the category_write permission should not be shared with anybody else, in the rare cases when granting this permission to another party is needed, site-wide admin intervention will be @@ -31,7 +36,8 @@ included. Note that the mapped subtree will not be a new tree. Therefore this option should be used only if an admin plans to use the subtree 'as is' and has no intention of making changes to -it.An alternative solution is available for admins who want to +it.
+An alternative solution is available for admins who want to create a tree by copying one of the existing trees and subsequently playing around with it (moving/adding/deleting categories). To accomplish that, they would have to create a new tree, go to the @@ -41,13 +47,19 @@ categories from the source trees and placing them in the new tree.
This operation can be performed several times, each time the copied -categories will be placed as toplevel categories of the tree.As far as unmapping is concerned, this operation doesn't delete -the mapping between categories and objects.
Permissions
The creator of the category tree is granted the +categories will be placed as toplevel categories of the tree.
+As far as unmapping is concerned, this operation doesn't delete +the mapping between categories and objects.
+Permissions
+The creator of the category tree is granted the category_tree_read, category_tree_write and category_tree_grant_permissions privileges.
-The operations one can perform on categories are:
+ +
+The operations one can perform on categories are:
+
- (a) changing of a parent
- (b) adding childen
- (c) deleting
- (d) editing
- (e) phasing in/out
- (f) changing sort key
-ad (d) You cannot delete a category that has children. Also, you +
ad (d) You cannot delete a category that has children. Also, you cannot delete a category that has objects mapped to it (do we want it or not?)
ad (e) The effect of phasing out a category is that users no longer @@ -57,8 +69,12 @@ operations.
ad (f) sort key is used to order children of the same parent category, that is the elements of the tree are sorted first by -parent, then by the sort key.
DatamodelThis table actually stores the information whether the tree is -side-wide or not.
+parent, then by the sort key. ++
+Datamodel +This table actually stores the information whether the tree is +side-wide or not.
+create table category_trees ( tree_id integer primary key constraint cat_trees_tree_id_fk @@ -67,8 +83,10 @@ constraint cat_trees_site_wide_p_ck check (site_wide_p in ('t','f')) ); -Here the tree's name and description is stored in different -translations.
++Here the tree's name and description is stored in different +translations.
+create table category_tree_translations ( tree_id integer constraint cat_tree_trans_tree_id_fk @@ -80,12 +98,14 @@ description varchar2(1000), primary key (tree_id, locale) ); -This table stores the tree hierarchy by holding the information +
This table stores the tree hierarchy by holding the information about the parent category. The tree is ordered by a nested index (left_ind, right_ind). Sorting is thus accomplished by means of a nested set. You can read a description of how nested sets work. This also describes how -to write queries that sort correctly when using categories.
+to write queries that sort correctly when using categories. ++create table categories ( category_id integer primary key constraint cat_category_id_fk @@ -102,8 +122,10 @@ left_ind integer, right_ind integer ); -Here the actual categories are stored together with different -translations.
++Here the actual categories are stored together with different +translations.
+create table category_translations ( category_id integer constraint cat_trans_category_id_fk @@ -115,7 +137,9 @@ description varchar2(4000), primary key (category_id, locale) ); -This table contains mapping between categories and objects
++This table contains mapping between categories and objects
+create table category_object_map ( category_id integer constraint cat_object_map_category_id_fk @@ -125,9 +149,11 @@ references acs_objects on delete cascade, primary key (object_id, category_id) ) organization index; -This is the table for the relation of trees and objects. +
This is the table for the relation of trees and objects. subtree_category_id comes to play in situations when you map a -subtree of an existing tree to an object.
+subtree of an existing tree to an object. +create table category_tree_map ( tree_id integer constraint cat_tree_map_tree_id_fk @@ -140,30 +166,42 @@ references categories, primary key (object_id, tree_id) ) organization index; -Known Limitations
+ +
+
+Known Limitations
+
- The tree order is the same for all translations.
- You can map a tree only once to a package (or other object).
- The number of objects mapped to a category is not shown yet. These results should be cached.
- When browsing categories all mapped categories should be shown for each object.
- There should be browsing widget easily used by other packages to let the user browse through all categorized objects.
-Integration with other packages
Here are the changes needed to be made to integrate with other -packages.
+
+Integration with other packages
+Here are the changes needed to be made to integrate with other +packages.
+index.adp
Provide an admin-link to /categories/cadmin/one-object?object_id=\@package_id\@ to let admins -map trees to the package instance.+map trees to the package instance.
+form-page.tcl
Use this in ad_form to display all mapped category trees and -selected categories (if editing an object):+selected categories (if editing an object): ++{category_ids:integer(category),multiple,optional {label "Categories"} {html {size 4}} {value {$object_id $package_id}}}+ Alternatively, you can include the following in your adp:<include src="/packages/categories/www/include/widget" object_id=\@object_id\@ package_id=\@package_id\@>+ In the processing part of ad_form use:category::map_object -remove_old -object_id $object_id $category_ids -
timo\@studio-k4.de - +
+timo\@studio-k4.de Index: openacs-4/packages/categories/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/categories/www/doc/index.adp,v diff -u -N -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/categories/www/doc/index.adp 21 Aug 2015 10:28:47 -0000 1.1.2.2 +++ openacs-4/packages/categories/www/doc/index.adp 25 Aug 2015 18:02:21 -0000 1.1.2.3 @@ -2,13 +2,14 @@{/doc/categories {Categories}} {Categories} Categories - - Release Notes
Please file bugs in the Bug Tracker.
docs\@openacs.org - +Release Notes
+Please file bugs in the Bug Tracker.
+
+docs\@openacs.org Index: openacs-4/packages/categories/www/doc/install.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/categories/www/doc/install.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/categories/www/doc/install.adp 20 Aug 2015 17:32:41 -0000 1.1.2.1 +++ openacs-4/packages/categories/www/doc/install.adp 25 Aug 2015 18:02:21 -0000 1.1.2.2 @@ -2,26 +2,22 @@{/doc/categories {Categories}} {Installation} Installation - - - + + \ No newline at end of file Index: openacs-4/packages/categories/www/doc/o.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/categories/www/doc/o.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/categories/www/doc/o.adp 20 Aug 2015 17:32:41 -0000 1.1.2.1 +++ openacs-4/packages/categories/www/doc/o.adp 25 Aug 2015 18:02:21 -0000 1.1.2.2 @@ -2,24 +2,26 @@ {/doc/categories {Categories}} {Object Names and IdHandler Service Contract} Object Names and IdHandler Service Contract + Object Names and IdHandler Service Contract
+Object Names
- -Object Names and IdHandler Service Contract
Object Names
When presenting a list of objects in a package not native to the objects (i.e. permissioning, community-member, category-usage) there has to be a fast and easy way to figure out the name of objects. Until now, this has been done by using something likeacs_objects.name(object_id)+ which essential means that for every object to be displayed (and since the mentioned pages are in no means scalable and therefore are likely to display a huge amount of objects) this pl/sql proc will have to figure out which package-specific pl/sql proc to call which itself will do at least one query to get the object-name.Obviously, this is highly undesirable since it is not scalable at all. Therefore, a new way had to be found to get the name of an -object:
+object: +------------------- -- NAMED OBJECTS -- ------------------- @@ -51,6 +53,7 @@ / show errors+ This means that every displayable object-type should no longer be derived from acs_objects, but from acs_named_objects and that by using triggers or extending the appropriate pl/sql procs, every @@ -59,11 +62,14 @@In that way, when having to display a list of objects, one can simply join the acs_named_objects table to get the names and package_ids in an easy and - more importantly - fast and scalable -way.
The only shortcomming of this solution is the disregard of +way.
+The only shortcomming of this solution is the disregard of internationalization, but in cases where there objects in more than one language, it should be the triggers / pl/sql procs task to make sure that acs_named_objects contains names in the default language -if possible.
IdHandler Service Contract
+if possible. +IdHandler Service Contract
+ Besides displaying the names of objects, some pages also want to provide links to the objects. Unfortunately, there currently is no way to do so. @@ -79,15 +85,17 @@ a package may have more than one type of objects (i.e. file folders, files, file versions), we can not simply store additional package information about which page to call to display an -object.The solution to this kind of problem is by not resolving the url +object.
+The solution to this kind of problem is by not resolving the url at all during display-time, but doing so at the time the user actually wants to see an object. The links would simply direct to /o/$object_id, which is a global virtual-url-handling page that will figure out the package instance url (by using acs_named_objects and the pl/sql proc) and then relying upon a Service Contract to get the local url - that means every package holding displayable objects should implement this interface for its -objects:
+objects: +declare v_id integer; begin @@ -149,6 +157,7 @@ ); end;+ The appropriate tcl-procs look like the following:ad_proc -public apm_pageurl { object_id } { @@ -165,7 +174,8 @@ } }+ Note that the name of the implementation has to be the object-type followed by _idhandler. -
timo\@studio-k4.de - +
+timo\@studio-k4.de Index: openacs-4/packages/categories/www/doc/requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/categories/www/doc/requirements.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/categories/www/doc/requirements.adp 20 Aug 2015 17:32:41 -0000 1.1.2.1 +++ openacs-4/packages/categories/www/doc/requirements.adp 25 Aug 2015 18:02:21 -0000 1.1.2.2 @@ -2,11 +2,11 @@{/doc/categories {Categories}} {Requirements} Requirements - - - View comments + + View comments on this page at openacs.org - Index: openacs-4/packages/dotlrn-homework/www/doc/design.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/dotlrn-homework/www/doc/design.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/dotlrn-homework/www/doc/design.adp 20 Aug 2015 17:47:46 -0000 1.1.2.1 +++ openacs-4/packages/dotlrn-homework/www/doc/design.adp 25 Aug 2015 18:02:21 -0000 1.1.2.2 @@ -2,10 +2,12 @@{/doc/dotlrn-homework {dotLRN Homework}} {dotLRN Homework Package Design Document} dotLRN Homework Package Design Document - - dotLRN Homework Package Design Document
-by Don BaccusIntroduction
+ +by Don Baccus +
+Introduction
+ The dotLRN Homework package provides a dropbox for students to upload homework files and for professors, teaching assistants and other graders to upload their comments and corrections to such @@ -17,11 +19,15 @@ class.Administrators can make subfolders in class homework dropbox folders. Typically this will be used to create a separate subfolder -for each homework assignment.
Administrators can ask to be notified by e-mail when a student +for each homework assignment.
+Administrators can ask to be notified by e-mail when a student uploads a new homework file. Likewise, students are notified when a -comment or correction file is uploaded by a grader.
Students can only access homework files they've uploaded +comment or correction file is uploaded by a grader.
+Students can only access homework files they've uploaded themselves along with each file's associated comments and -corrections files.
Two applets and their associated portlets are provided:
+corrections files. +
+Two applets and their associated portlets are provided:
+
- User applet
When added to a class home portal page students will see a list of folders and links to homework files they've uploaded for the @@ -35,12 +41,15 @@ portal page.
- Admin applet
- -
The admin applet allows administrators to enable or disable e-mail alerts sent when a student uploads a new homework file.
In addition several display pages are provided to view or +
In addition several display pages are provided to view or download file revisions, to view or download comment files associated with a particular homework file, to delete files, move them from one subfolder to another, and so forth. The actions that are available depend on whether the user is a student or -administrator.
Implementation
+administrator. +Implementation
+ The implementation is based on the standard OpenACS 4 File Storage package. The requirements and design documents for the File Storage package apply directly to the dotLRN Homework package. @@ -51,8 +60,8 @@ comment/correction files to each homework file. Actions are restricted by use of the acs permissions system. The user interface has been modified slightly to simplify the uploading of -comment/correction files by graders.ad_form is used to build forms in the dotLRN Homework package. +comment/correction files by graders.
+ad_form is used to build forms in the dotLRN Homework package. This means that the look and feel of all the forms generated by the package can be changed by creating a single new form template file.
- Index: openacs-4/packages/file-storage/www/doc/design.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/file-storage/www/doc/design.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/file-storage/www/doc/design.adp 20 Aug 2015 17:47:47 -0000 1.1.2.1 +++ openacs-4/packages/file-storage/www/doc/design.adp 25 Aug 2015 18:02:21 -0000 1.1.2.2 @@ -2,84 +2,110 @@{/doc/file-storage {File Storage}} {File Storage Design Document} File Storage Design Document - - File Storage Design Document
-by Kevin Scaldeferri, + +by Kevin Scaldeferri +, modified by Jowell S. -Sabino for OpenACS. -I. Essentials
+Sabino + for OpenACS. +
+I. Essentials
+
- User directory: /file-storage/
- Tcl procedures: /tcl/file-storage-defs.tcl
- Requirements document: /doc/requirements/file-storage.html
- Data model: file-storage-create.sql
-II. Introduction
We have our own file-storage application because we want all +
II. Introduction
+We have our own file-storage application because we want all users to be able to collaboratively maintain a set of documents. Specifically, users can save their files to our server so that they -may:
+may: +
+
- Organize files in a hierarchical directory structure
- Upload using Web forms, using the file-upload feature of Web browsers (potentially SSL-encrypted)
- Grab files that are served bit-for-bit by the server, without any risk that a cracker-uploaded file will be executed as code
- Retrieve historical versions of a file
-We want something that is relatively secure, and can be extended +
We want something that is relatively secure, and can be extended and maintained by any ArsDigita programmer, i.e., something -that requires only AOLserver Tcl and Oracle skills.
In ACS 4, File Storage can be implemented on top of the Content +that requires only AOLserver Tcl and Oracle skills.
+In ACS 4, File Storage can be implemented on top of the Content Repository. Thus, there is no data model associated with File Storage. It is only a UI and a small set of Tcl and PL/SQL library procedures. The actual storage and versioning is relegated to the -Content Repository.
III. Historical Considerations
File Storage was created to provide a mechanism for +Content Repository.
+III. Historical Considerations
+File Storage was created to provide a mechanism for non-technical users to collaborate on a wide range of documents, with minimum sysadmin overhead. Specifically, it allowed clients to exchange design documents (often MS Word, Adobe PDF, or other proprietary desktop file formats) that changed frequently without -having to get bogged down by sifting through multiple versions.
IV. Competitive Analysis
Why is a file-storage application useful?
If you simply give everyone FTP access to a Web-accessible +having to get bogged down by sifting through multiple versions.
+IV. Competitive Analysis
+Why is a file-storage application useful?
+If you simply give everyone FTP access to a Web-accessible directory, you are running some big security risks. FTP is insecure and passwords are transmitted in the clear. A cracker might sniff a password, upload Perl scripts or ADP pages, then grab those URLs from a Web browser. The cracker is now executing arbitrary code on your server with all the privileges that you've given your Web -server.
The File Storage application is not a web-based file system, and +server.
+The File Storage application is not a web-based file system, and can not be fairly compared against such systems. The role of File Storage is to provide a simple web location where users can share a versioned document. It does not allow much functionality with respect to aggregate file administration (ex. selecting all files -of a given type, or searching through specified file types).
V. Design Tradeoffs
Folder Permissions
Previous versions of File Storage have not included folder +of a given type, or searching through specified file types).
+V. Design Tradeoffs
+Folder Permissions
+Previous versions of File Storage have not included folder permissions. (However they did have a concept of private group trees.) The reasons for this were to simplify the code and the user experience. However, this system actually caused some confusion (e.g., explicitly granting permission to an outsider on a file in a group's private tree did not actually give that person access to the file) and was not as flexible as people desired. The ACS 4 version includes folder read, write and delete -permissions.
Note that this can create some funny results. For example, a +permissions.
+Note that this can create some funny results. For example, a user might have write permission on a folder, but not on some of its parent folders. This can cause the select box provided for -moving and copying files to look odd or misleading.
Deletion of Files
Previous versions of File Storage allowed only administrators to +moving and copying files to look odd or misleading.
+Deletion of Files
+Previous versions of File Storage allowed only administrators to actually delete content (although users could mark content as "deleted" using a toggle in the data model, deleted_p.) However, the proper use of versioning should allow users to avoid accidentally losing their files. So, in this version, if a person -asks to delete a version or a file, we really delete it.
Use of Content Repository
Basing this system on the Content Repository provides a wealth +asks to delete a version or a file, we really delete it.
+Use of Content Repository
+Basing this system on the Content Repository provides a wealth of useful functionality for File Storage with no additional development costs. However, it may also constrain the system -somewhat.
The Content Repository's datamodel has been extended to include +somewhat.
+The Content Repository's datamodel has been extended to include an attibute to store the filesize. Unfortunately, the Content Repository does not automatically do this, since files may be stored on the filesystem (the Content Repository thus serving as a catalog to keep track of file location and some metadata, but not the filesize). The filesize is therefore calculated whenever a file is inserted in the Content Repository by the external program (the webserver's database driver) doing the insertion into the -database..
The content_revision is subtyped as a "file-storage-item" to +database..
+The content_revision is subtyped as a "file-storage-item" to allow site-wide search to distinguish file storage objects in its -search results. This feature is not implemented yet, however.
Permissions Design
Permissions were chosen to make as much use as possible of the +search results. This feature is not implemented yet, however.
+Permissions Design
+Permissions were chosen to make as much use as possible of the predefined privileges while keeping the connotative value of each privilege clear. The permissions scheme is vaguely modeled off Unix file permissions, with somewhat less overloading. In particular, we define a delete privilege rather than overloading the write permission. Also, execute privileges have no meaning in this -context.
+context. +
+
Folder File Version @@ -92,27 +118,35 @@ -admin modify permission grants and read, write and delete privileges Some notes: the admin privilege implies the read, write and +
Some notes: the admin privilege implies the read, write and delete privileges. It may be the case that a user has delete permission on a folder or file, but not on some of its child items. This will block attempts to delete the parent item. Finally, the -write permission does not have any meaning for versions.
VI. API
For the most part, File Storage will provide wrappers to the -Content Repository APIs.
PL/SQL API
File Storage provides public PL/SQL APIs either as wrappers to +write permission does not have any meaning for versions.
+VI. API
+For the most part, File Storage will provide wrappers to the +Content Repository APIs.
+PL/SQL API
+File Storage provides public PL/SQL APIs either as wrappers to the Content Repository API, or more involved functions that calls multiple Content Repository PL/SQP functions. One reason for doing this is to abstract from the Content Repository datamodel and naming conventions, due to the different way File Storage labels -its objects.
The main objects of File Storage are "folders" and "files". A +its objects.
+The main objects of File Storage are "folders" and "files". A "folder" is analogous to a subdirectory in the Unix/Windows-world filesystem. Folder objects are stored as Content Repostory folders, -thus folders are stored "as is" in the Content Repository.
"Files", however, can cause some confusion when stored in the +thus folders are stored "as is" in the Content Repository.
+"Files", however, can cause some confusion when stored in the Content Repository. A "file" in File Storage consists of meta-data, and possibly multiple versions of the file's contents. The main meta-data of a "file" is its "title", which is stored in the Content Repository's "name" attribute of the cr_items table. The "title" of a file should be unique within a subdirectory, although a directory may contain a file and a folder with the same -"title".
Each version of a file is stored as a revision in cr_revisions +"title".
+Each version of a file is stored as a revision in cr_revisions table of Content Repository. The Content Repository also allows some meta-data about a version to be stored in this table, and indeed File Storage uses attributes of the cr_revisions table are @@ -124,13 +158,17 @@ Content Repository API makes sure that the naming convention is corect: cr_items.name attribute stores the title of a file and all its versions, while the cr_revisions.title attribute stores the -filename of the version uploaded into the Content Repository.
Meta-data about a version of a file stored in Content Repository +filename of the version uploaded into the Content Repository.
+Meta-data about a version of a file stored in Content Repository are the size of the version (stored in cr_revisions.content_length) -and version notes (stored in cr_revisions.description).
There are two internal PL/SQL functions that do not call the +and version notes (stored in cr_revisions.description).
+There are two internal PL/SQL functions that do not call the Content Repository API, however:
get_root_folderandnew_root_folder, defined in the file_storage PL/SQL package -Tcl API
+
+ + Tcl API
+
children_have_permission_p
children_have_permission_p [ -user_id user_id ] item_idprivilegeThis procedure, given a content item and a privilege, @@ -144,7 +182,8 @@-+
+
fs_context_bar_list
fs_context_bar_list [ -final final ] item_idConstructs the list to be fed to ad_context_bar @@ -159,7 +198,8 @@-+
+
fs_file_downloader
fs_file_downloader connkeySends the requested file to the user. Note that the @@ -173,7 +213,8 @@-+
+
fs_file_p
fs_file_p file_idReturns 1 if the file_id corresponds to a file in the @@ -184,7 +225,8 @@-+
+
fs_folder_p
fs_folder_p folder_idReturns 1 if the folder_id corresponds to a folder in @@ -195,7 +237,8 @@-+
+
fs_get_folder_name
fs_get_folder_name folder_idReturns the name of a folder. @@ -205,7 +248,8 @@-+
+
fs_root_folder
fs_root_folder [ -package_id package_id ]Returns the root folder for the file storage system. @@ -215,7 +259,8 @@-+
+
fs_version_p
fs_version_p version_idReturns 1 if the version_id corresponds to a version in @@ -226,10 +271,13 @@-VII. Data Model Discussion
File Storage uses only the Content Repository data model. There +
VII. Data Model Discussion
+File Storage uses only the Content Repository data model. There is one additional table,
fs_root_folders, which maps between package instances and the corresponding root folders in the -Content Repository.Inserting a row into the table fs_root_folders occurs the first +Content Repository.
+Inserting a row into the table fs_root_folders occurs the first time the package instance is visited. The reason is that there is no facility in APM to insert a row in the database everytime a package instance is created (technically, there is no "on insert" @@ -248,7 +296,8 @@ returns the newly created folder identifier as the root folder for this package instance. Subsequent visits to the package instance will detect the root folder, and will then return the root folder -identifier.
There is an "on delete cascade" constraint imposed on the +identifier.
+There is an "on delete cascade" constraint imposed on the package_id attribute of fs_root_folders. The reason for this is that whenever the package instance is deleted by the site administrator, it automatically deletes the mapping between APM and @@ -261,21 +310,26 @@ the package identifier attribute of fs_root_folders will cause all objects belonging to the instance of File Storage deleted to be orphaned in the database, since the root folder is the crucial link -from which all content is referenced!
The solution is (hopefully) more elegant: an "before on delete" +from which all content is referenced!
+The solution is (hopefully) more elegant: an "before on delete" trigger that first cleans up all contents under the root folder identifier before the root folder identifier is deleted by APM. This trigger walks through all the contents of the instance of File Storage, and starts deleting from the "leaves" or end nodes of the file tree up to the root folder. Later improvements in Content Repository will allow archiving of the contents instaed of actually -deleting them from the database.
VIII. User Interface
The user interface attempts to replicate the file system +deleting them from the database.
+VIII. User Interface
+The user interface attempts to replicate the file system metaphors familiar to most computer users, with folders containing files. Adding files and folders are hyperlinked options, and a web form is used to handle the search function. Files and folders are presented with size, type, and modification date, alongside hyperlinks to the appropriate actions for a given file. Admin functions will be presented alongside the normal user action when -appropriate.
IX. Configuration/Parameters
There are two configuration parameters in this version of File +appropriate.
+IX. Configuration/Parameters
+There are two configuration parameters in this version of File Storage. The first parameter MaximumFileSize is the maximum size of uploaded files, which should be self-explanatory. The other parameter is a flag that indicates to the package whether @@ -289,7 +343,8 @@ for the site administrator to store the entire directory containing the Content Repository files (in particular, pageroot/content-repository-content-files) when storing -files in the fiesystem.
When a file is stored in the Content Repository, it first +files in the fiesystem.
+When a file is stored in the Content Repository, it first queries the parameter StoreFilesInDatabaseP to determine how the new file will be stored. Thus, it is important that this parameter should be changed only at package instance creation, or @@ -299,8 +354,11 @@ the file is uploaded. Although all functionality provided by File Storage will continue to work (copy, move, delete, etc.), backing up the contents will be more complicated if the parameter is -changed.
All of the other parameters in previous versions have been made -obsolete by ACS 4 features like site-nodes and templating.
X. Future Improvements/Areas of Likely Change
+changed. +
+All of the other parameters in previous versions have been made +obsolete by ACS 4 features like site-nodes and templating.
+X. Future Improvements/Areas of Likely Change
+
- Allow people to comment on files (and versions and folders?)
- Implement searching on content (waiting for site-wide-search)
- Allow users to toggle folders open and closed @@ -322,14 +380,23 @@ display "application/msword" instead of "MS Word Document", for example. We could use a method of determining the canonical long form of a MIME type.
-XI. Authors
- System creator:
-3.x : David Hill +XI. Authors
++
- System creator:
+3.x : David Hill and Aurelius Prochazka
4.x : Kevin Scaldeferri -
- System owner
Kevin -Scaldeferri
- Documentation author
Kevin -ScaldeferriXII. Revision History
+ +
++
- System owner
Kevin +Scaldeferri++
- Documentation author
Kevin +Scaldeferri+XII. Revision History
+
Document Revision # Action Taken, Notes When? By Whom? @@ -339,5 +406,6 @@ - 0.2 Revised after review by Josh 11/16/2000 Kevin Scaldeferri, Josh Finkler
kevin\@arsdigita.com - +
+kevin\@arsdigita.com Index: openacs-4/packages/file-storage/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/file-storage/www/doc/index.adp,v diff -u -N -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/file-storage/www/doc/index.adp 21 Aug 2015 10:28:48 -0000 1.1.2.2 +++ openacs-4/packages/file-storage/www/doc/index.adp 25 Aug 2015 18:02:21 -0000 1.1.2.3 @@ -2,9 +2,12 @@{/doc/file-storage {File Storage}} {File-Storage Documentation} File-Storage Documentation - - - File-Storage Documentation
+
kevin\@arsdigita.com - + +File-Storage Documentation
+Release Notes
Please file bugs in the Bug Tracker.
Release Notes
+Please file bugs in the Bug Tracker.
+
+ +kevin\@arsdigita.com Index: openacs-4/packages/file-storage/www/doc/requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/file-storage/www/doc/requirements.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/file-storage/www/doc/requirements.adp 20 Aug 2015 17:47:47 -0000 1.1.2.1 +++ openacs-4/packages/file-storage/www/doc/requirements.adp 25 Aug 2015 18:02:21 -0000 1.1.2.2 @@ -2,26 +2,35 @@{/doc/file-storage {File Storage}} {File-Storage Application Requirements} File-Storage Application Requirements - - File-Storage Application Requirements
-by Kevin ScaldeferriI. Introduction
This document describes the requirements for ACS File-Storage + +by Kevin Scaldeferri +
I. Introduction
+This document describes the requirements for ACS File-Storage application. The file-storage application allows individuals to place their files on a publicly accessible web site and share them with other members of that web community or with the public at -large.
II. Vision Statement
The goal of a Web community is to facilitate the sharing of +large.
+II. Vision Statement
+The goal of a Web community is to facilitate the sharing of information. This information can come in a variety of forms: text, images, executable files, and web pages. The file storage application should provide a convenient way for users to share information in any of these formats. Users should be able to determine which individuals or groups should be allowed to read particular items and who should be allowed to upload new -versions.
Since information is only useful if you can find what you're +versions.
+Since information is only useful if you can find what you're looking for, files in the file storage system should be searchable, both from within the application and through any site-wide search -facilities.
III. System/Application Overview
The File-Storage application will consist primarily of a user +facilities.
+III. System/Application Overview
+The File-Storage application will consist primarily of a user interface that allows individuals to manage their file-storage -folder(s) and to see other people's publicly accessible files.
IV. Use Case and User Scenarios
Using File-Storage to Run a Project
In the course of her job at Acme Publishing Company, Ursula +folder(s) and to see other people's publicly accessible files.
+IV. Use Case and User Scenarios
+Using File-Storage to Run a Project
+In the course of her job at Acme Publishing Company, Ursula User is working with people from several different offices with whom she needs to exchange pictures and Excel spreadsheets detailing cost estimates, and collaboratively write contracts using @@ -30,7 +39,8 @@ be able to look at older versions if need be to track the evolution of the project. If the project is large, Ursula will also need to be able to find all the documents pertaining to a particular issue -- so she will need a full-text search feature.
For each project, Ursula makes a folder on the file-storage +- so she will need a full-text search feature.
+For each project, Ursula makes a folder on the file-storage system and gives read, write, and edit permission to the group of people she is working with for that project. Then she makes subfolders for each of the tasks for that project and asks @@ -48,7 +58,9 @@ completed, if Ursula is considerate of the maintainers of the site and of other users, she will clean-up after herself, downloading the canonical version of all the documents to her local machine and -deleting the files from the server.
Administer File-Storage
+deleting the files from the server.
+Administer File-Storage
+Annie Admin primarily has the job of periodically cleaning up after users. If disk space is tight on the server, she may want to look for files that haven't been accessed in a long @@ -57,42 +69,68 @@ herself if the user can't be contacted or is unresponsive. Depending on the precise permissions implementation, Annie may occasionally need to intercede when the owner of a file -accidentally revokes their own permission to access the file.
V. Related Links
+accidentally revokes their own permission to access the file. +
+V. Related Links
+VI.A. Requirements: Data Model
10 The Data Model
-10.1 each file should have a unique identifier
+
VI.A. Requirements: Data Model
+10 The Data Model
++10.1 each file should have a unique identifier
+10.2 each version of a file should have a unique -identifier
-10.3 each file should have an associated owner
-10.4 each version should have an associated owner
+identifier
++10.3 each file should have an associated owner
++10.4 each version should have an associated owner
+10.5 files will be organized in a hierarchical set of -folders
+folders
+10.6 each version of each file will have individual read, write, delete, comment, and administer permissions associated with -it
VI.B. Requirements: Administrator Interface
20 Administrator Interface
+it
+VI.B. Requirements: Administrator Interface
+20 Administrator Interface
+20.1 the administrator should be able to view all files -in the file-storage system
+in the file-storage system
+20.2 the administrator should be able to edit, delete, or -alter permissions for any file belonging to any user
VI.C. Requirements: User Interface
30 User Interface
+alter permissions for any file belonging to any user
+VI.C. Requirements: User Interface
+30 User Interface
+30.1 a user should be able to create folders and -subfolders in which he can place his files
+subfolders in which he can place his files
+30.2 a user should be able to add new files and new -versions of files
+versions of files
+30.3 a user should be able to move files to different -folders or sub-folders
+folders or sub-folders
+30.4 a user should be able to delete folders and -individual files
+individual files
+30.5 a user should be able to specify permissions for any -user or group on any folder, file, or version.
+user or group on any folder, file, or version.
+30.6 a user should be able to download any version which -is accessible to him
+is accessible to him
+30.7 a user should be able to view and/or edit other user's files if the user has been granted individual or group -permission with access to the files
+permission with access to the files
+30.8 a user should be able to search the text of the documents stored in the file-storage system (requires full-text search capability from the database - in the case of Oracle, -requires InterMedia)
VII. Revision History
+requires InterMedia) +
+VII. Revision History
+
Document Revision # Action Taken, Notes When? By Whom? @@ -102,7 +140,9 @@ - 0.3 Revised based on review by Josh Finkler 6 November 2000 Kevin Scaldeferri, Josh Finkler
kevin\@arsdigita.com +
+kevin\@arsdigita.com + Last Modified: $Id: requirements.html,v 1.3 2005/05/26 08:28:46 maltes Exp $ - Index: openacs-4/packages/general-comments/www/doc/design.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/general-comments/www/doc/design.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/general-comments/www/doc/design.adp 20 Aug 2015 17:47:47 -0000 1.1.2.1 +++ openacs-4/packages/general-comments/www/doc/design.adp 25 Aug 2015 18:02:21 -0000 1.1.2.2 @@ -2,14 +2,13 @@{/doc/general-comments {General Comments}} {Design Document} Design Document - - ++-1.2. Design Document
1.2.1. Essentials
@@ -170,7 +169,8 @@
Last modified: $Id: design.html,v 1.2 2014/10/27 16:41:44 victorg Exp $
++ - Index: openacs-4/packages/general-comments/www/doc/dev-guide.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/general-comments/www/doc/dev-guide.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/general-comments/www/doc/dev-guide.adp 20 Aug 2015 17:47:47 -0000 1.1.2.1 +++ openacs-4/packages/general-comments/www/doc/dev-guide.adp 25 Aug 2015 18:02:21 -0000 1.1.2.2 @@ -2,13 +2,12 @@{/doc/general-comments {General Comments}} {Developer's guide} Developer's guide - - ++ -++ - Index: openacs-4/packages/general-comments/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/general-comments/www/doc/index.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/general-comments/www/doc/index.adp 20 Aug 2015 17:47:47 -0000 1.1.2.1 +++ openacs-4/packages/general-comments/www/doc/index.adp 25 Aug 2015 18:02:21 -0000 1.1.2.2 @@ -2,8 +2,6 @@{/doc/general-comments {General Comments}} {General Comments} General Comments - - ++- Index: openacs-4/packages/general-comments/www/doc/users-guide.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/general-comments/www/doc/users-guide.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/general-comments/www/doc/users-guide.adp 20 Aug 2015 17:47:48 -0000 1.1.2.1 +++ openacs-4/packages/general-comments/www/doc/users-guide.adp 25 Aug 2015 18:02:22 -0000 1.1.2.2 @@ -2,14 +2,14 @@
Next @@ -66,4 +65,3 @@{/doc/general-comments {General Comments}} {User's guide} User's guide - -
General Comments - Prev {/doc/news {News}} {News Design Document} News Design Document - - News Design Document
-by Stefan DeuschI. Essentials
+ +by Stefan Deusch +
+
+I. Essentials
+
- User directory: /news/
- Tcl procedures: /tcl/news-procs.tcl
- Requirements document: /doc/news/requirements.html
- Data model: news-create.sql , news-sws.sql
-II. Introduction
+II. Introduction
+ Most Web services and almost all corporate sites have a comany.com/news/ service. These can be used in a variety of ways, e.g. for advertising or dissemination of related news items. News @@ -24,19 +28,22 @@ news coverage where several organizations are using the same ACS serverIII. Historical Considerations
+ News applications previous to ACS 4 were less integrated into the site and had less functionality. This version scopes instances implicitly through use of the acs-permissioning system. The old news allowed to edit the items, the new one allows version control. The administrator can switch back to a historic version of a news item.IV. Competitive Analysis
+ The News application is consistent with the functionality of similar systems on the Internet. It is built with ACS 4 and relies on the object oriented nature of ACS 4. It is best used in conjunction with other ACS applications such as general-comments, site-wide-search, and file storage.V. Design
+ Published or archived news items are presented as entries in a hyperlinked list. Single news items are presented by taking advantage of the ACS Templating system. The default news template @@ -50,6 +57,7 @@ \@creator_link\@ + as input. Publishers may wish to provide their own templates, however even more flexibility can be introduced by supplying the news body in HTML format. If someone submits a news body with @@ -63,10 +71,14 @@ and install the ACS4 file-storage module from the acs-repository, upload some photographs in gif or jpeg format, and then link it into the HTML news body, somewhat like this: <img -src="http://myserver.org/file-storage/download/Fig1.gif">If someone submits a news body with inconsistent HTML tags, the +src="http://myserver.org/file-storage/download/Fig1.gif">
+If someone submits a news body with inconsistent HTML tags, the News application attempts to close these tags in the preview -page.
VI. API
+page. +VI. API
+ Much of the API is covered in the news-create.sql + file. The news package body holds all of the PL/SQL functions and procedures.@@ -78,12 +90,16 @@ item (not used)
+ The Tcl procedures are, see /tcl/news-procs.tcl + file.- news.revision_activate: make a revision the active revision
- news_items_archive: archives items at a certain date
- news_items_make_permanent: removes archival date from items
- news_items_delete: deletes news items
-VII. Data Model Discussion
+ +VII. Data Model Discussion
+ The News application makes use of the exisiting ACS Content Repository service. A news item consists of a row-entry in the table cr_item, where all of the meta-information that isn't already @@ -112,33 +128,40 @@ approval_ip varchar2(50) ); + Note that different package instances of the News application can be distinguished by the column 'package_id' (and not by the inherited context_id in acs_objects). We therefore need only a single cr_folder named 'news' to hold all news items.The data model in the context of the content repository are -futher characterized by following:
+futher characterized by following: +
+ A reminder to the column release_date is necessary here: Its granularity is only one day, i.e. the relase date is for instance 2001-01-01 00:00 (always at midnight). If someone wants to present a view of 'new items' since last login (which can be more than once since 00:00), one can use cr_news.approval_date for differentiating since this is time-stamped by sysdate.
- The items are assigned to the folder 'news' in the content repository.
- The PL/SQL API provides procedures and functions to create, delete, approve, archive, query, release, or revise a news item.
- A new revision generates an entry in cr_news and cr_revisions in parallel and updates the live_revision in cr_items.
- The release date is stored in the publish_date column of cr_revisions,
- The archive_date is supplemented by cr_news.
Permissions
+ With the ACS4 permissions model, the news administrator need no longer coincide with the site administrator. This need only be the case right after installation. The News application has a hierarchical set of permissions which can be assigned to any party -as needed. The news root privilege isnews_adminwhich -comprisesnews_create, news_delete,and -news_read. +as needed. The news root privilege isnews_admin+ which +comprisesnews_create, news_delete,+ and +news_read+.By default, the
news_adminpermission inherits from the site-wide admin. Thenews_readpermission is assigned to the public so that all users, including non-registered @@ -150,31 +173,42 @@ to 'open'. The news privileges can be changed in /permissions/ by the administrator on the /news/admin/index page. The needs of an individual site, e.g. sharing the news administration duties among -several individuals, are thus covered.Legal Transactions
User Pages
+several individuals, are thus covered. +
+Legal Transactions
+User Pages
+
- View published news item list: index?view=active
- View archived news item list: index?view=archive
- View one news item: revision
- Preview one news item before publishing/approving: preview
-News Administrator Pages
+
+News Administrator Pages
+
- View one news item with administrative information: admin/revision
- Administer news items: admin/index
- Administer one news item: admin/item
- Add/suggest a new news item: item-create
- Edit existing news coverage by adding a revision: admin/revision-add
- Archive existing news coverage: admin/process?action=archive
- Make permanent existing news coverage: admin/process?action=make_permanent
- Approve existing news coverage: admin/approve
- De-activate existing news coverage: admin/revoke
- Delete existing news coverage: admin/process?action=delete
- Set one revision the active one: admin/revision-set-active
-VIII. User Interface
+VIII. User Interface
+ The publicly accessible pages are in the root directory of the mounted instance. The administrative pages are in /news/admin/. No privilege check is needed in the news/admin/ directory.The corresponding links for Administer and Create news item only appear for parties which possess the appropriate privileges. Viewers not authorized to view the index page (i.e. parties who were denied the
news_readpermission) are -shown the the site-wide 'not-authorized' template.The news gateway defaults to serving the parameter +shown the the site-wide 'not-authorized' template.
+The news gateway defaults to serving the parameter
DisplayMax, see sec. XI below, number of news items or archived items. The rest of the items can be viewed with a centered paging link at the bottom of the page. The linkarchived -items | live itemsappears if such exist.The /admin/index page shows a table of the active revisions of -each news item. News items can have the status of:
+items | live items appears if such exist. +
+The /admin/index page shows a table of the active revisions of +each news item. News items can have the status of:
++ The /admin/index page has a dimensional slider to select items with the corresponding status. To each selected view, a SELECT box with allowable operations (on the items checked at their checkbox in the @@ -189,9 +223,12 @@ changes. The /admin/item administration page shows the audit history of an item in a similar format as that of the files shown in cvs.arsdigita.com. be -added.
- unapproved (only if a non-news-admin uploaded something), the news_admin is approved automatically
- approved and awaiting release
- published (= approved and live)
- archived
Function of the archive date: The archive status is either a +added.
+Function of the archive date: The archive status is either a date in the future after the release date or null for permanently -live items.
IX. Making News Searchable with Site-Wide-Search
+live items. +IX. Making News Searchable with Site-Wide-Search
+ Follow the setup instruction in site-wide-search and read the design doc. You have to follow specifically these steps:@@ -212,10 +249,13 @@ -
To drop an instance of the News application correctly, follow -these steps:
+
+To drop an instance of the News application correctly, follow +these steps:
++ As can be seen from the function news__sws.sws_req_permission each searchable item requires an access permission. For users with the privilege 'news_admin', no permission (null) is required and all @@ -226,6 +266,7 @@ directory of site-wide-search, don't distinguish between 'live' and 'archived' items.
- drop news, and source news-sws-drop.sql
- source site-wide-search/sql/content-revision-sws-drop.sql
- source sws-package-all-drop.sql
X. General Comments
+ This release allows general comments using the general-comments package. The policy of general comments is determined by the parameter SolicitCommentsP, see below. In order to work correctly, @@ -237,7 +278,9 @@The most important integration of the comments facility is reflected in the news.delete procedure of the package news. Before the news item is deleted, all possible dependent comments inlcuding -picture attachments are dropped.
XI. Parameters
+picture attachments are dropped. +XI. Parameters
+ The news application has three customizable parameters which have to be set for each package instance through the site-map manager.@@ -248,32 +291,42 @@ searching news items with site-wide-search (must be installed).
- SolicitCommentsP...[1,0] whether we allow comments on a news item or not
-XII. Acceptance Tests
+XII. Acceptance Tests
+ You should test adding, viewing, editing, changing revisions, changing status and deleting a news item:+ Uploads of up to 10.000-character news items was tested successfully. HTML uploads appear correctly. However, some HTML tags are filtered site-wide against malicious spamming. The -site-wide admin can turn them on/of at setting ACS Kernel parameters at ACS Kernel +site-wide admin can turn them on/of at setting ACS Kernel parameters + at ACS Kernel [set parameters].
- Go to /news/ and click on the Administer link.
- Add a news item
- Verify that the item shows up on the admin side and the user side with the correct number of days left for display.
- Verify that the new revision is active, and that it is displayed on the user side.
- On the admin side, archive the item.
- Ensure that the user now sees it as an archived item.
- On the admin side, make the item permanent.
- Ensure that the user now sees it as a live item.
- Delete the item.
+ Pure text uploads preserve their formatting from the textarea - a <pre> tag is wrapped around. That way the textarea for entering the news body is used as a formatting editor. -XIII. Future Improvements
+
XIII. Future Improvements
+
- Use e-mail notification on submission and release, such as supplied by ACS Notification in PL/SQL only.
- Allow for more MIME types, especially Microsoft Word, and use the corresponding Intermedia filter to render as HTML.
- Add news categorization to the data model that allows to order news articles by categories without creating new application instances (e.g. sports, education, health, literature, music , politics, ...) - this also needs a UI to create categories and a mapping table.
-XIV. Authors
-Please mail suggestions or bug reports to Stefan DeuschXV. Revision History
+ +
XIV. Authors
+ +Please mail suggestions or bug reports to Stefan Deusch +XV. Revision History
+- Index: openacs-4/packages/news/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/news/www/doc/index.adp,v diff -u -N -r1.1.2.5 -r1.1.2.6 --- openacs-4/packages/news/www/doc/index.adp 21 Aug 2015 10:49:22 -0000 1.1.2.5 +++ openacs-4/packages/news/www/doc/index.adp 25 Aug 2015 18:02:22 -0000 1.1.2.6 @@ -2,26 +2,35 @@
Document Revision # Action Taken, Notes When?(mm/dd/yyyy) By Whom? @@ -288,4 +341,3 @@ 1.2 Alpha release wrap up 1/25/2001 Stefan Deusch {/doc/news {News}} {News} News - - - News
Document overview
+
+News
+Document overview
+
Requirements Vision of a News application. - Design Details on implementation Release Notes
-The current release is 4.0.1. It is available from ACS package repository. +Release Notes
+ +The current release is 4.0.1. It is available from ACS package repository +.Permissions
+ If you install the package as site-wide admin, you have full permission for any function in news. If you are the site-wide admin and want somebody else to do the news administrator, assign him/her -the privilege 'news_admin' in /permissions/. If you are not the site-wide +the privilege 'news_admin' in /permissions/ +. If you are not the site-wide admin, you must ask the latter to do so.Reporting bug
-Please file bugs in the Bucktracker. -
Stefan -Deusch
+ +Please file bugs in the Bucktracker +. +
+Stefan +Deusch +
+ Last modified: $Id: index.html,v 1.3.22.2 2015/08/21 10:28:48 gustafn Exp $ - Index: openacs-4/packages/news/www/doc/requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/news/www/doc/requirements.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/news/www/doc/requirements.adp 20 Aug 2015 17:47:48 -0000 1.1.2.1 +++ openacs-4/packages/news/www/doc/requirements.adp 25 Aug 2015 18:02:22 -0000 1.1.2.2 @@ -2,13 +2,15 @@{/doc/news {News}} {News Package Requirements} News Package Requirements - - News Package Requirements
-by Stefan DeuschI. Introduction
+ +by Stefan Deusch +I. Introduction
+ This document outlines the requirements for the ArsDigita News application built on the ACS 4.0 platform.II. Vision Statement
+ Communities are formed with the goal of disseminating information relevant to their members. Online communities have the advantage of an ideal mechanism for disseminating this information in a timely @@ -30,11 +32,16 @@ as well as for a closely moderated corporate publication channel. News is also different from the Press application insofar as press items typically derive from sources external to the organization in -question.III. System/Application Overview
+question. +III. System/Application Overview
+ The News application shall make use of the content -repository service. Each news item consists of an entry in -cr_itemsand keeps track of revisions in -cr_revisions. Additional attributes of a news item are +repository + service. Each news item consists of an entry in +cr_items+ and keeps track of revisions in +cr_revisions+. Additional attributes of a news item are stored in an extra table, namely, title, body, release date, archive date, templating info, and MIME type. The News application includes a simple templating system which allows it to @@ -50,16 +57,20 @@ the news application,- a news administrator with the same privileges for a specific instance of news,
- a registered user interface with creation privileges,
- a viewer interface for viewing the news items with the option to leave comments.
-IV. Use-cases and User-scenarios
+ +IV. Use-cases and User-scenarios
+ The different classes of users are of the following categories: adminstrators, submitters, and readers.
+ The administrative power is either site-wide or instance-wide. Typical user scenarios are as such:+ Suppose that www.company.com is running an ACS 4.0 based site. On this site they have a Boston office subcommunity. Jane Administrator is the subsite admininstator for the Boston office @@ -79,14 +90,20 @@ the Boston Office, then by visiting the Boston Office News site Joe can read up on any current Boston office related news that has been posted as such. -
- Community members use the News package to see current news postings.
- Subsite administrators use the News package to post news of interest to community members.
V. Related Links
+
+V. Related Links
+
- Design document (not available yet)
- Test plan (Not available yet)
-VI. Requirements
VI.1 Data Model
+VI. Requirements
+VI.1 Data Model
+ 10.10 The News application should use the ACS Content Repository and/or ACS Content as well as tie in with the ACS Interface service package.
+ 10.10.10 cr_news: subtype cr_revisions to define news content type
+ 10.10.20 news_templates: use file system for new templates, no extra table10.30 Privilege
@@ -96,7 +113,8 @@ 10.30.30 Provide registered user level privileges: news_create
10.30.40 Provide a public level privilege: news_read
10.30.50 Specify the intended parent/child relations between these -privileges.10.40 Parameters
+
+privileges.10.40 Parameters
10.40.10 Provide a parameter 'MakeSearchable' which indicates whether news item content should be accessible through the ACS Content service package
@@ -112,64 +130,99 @@ 10.40.50 Provide a 'NotifyByEmailOnUploadP' if the news administrator should be notified via email upon news items submission
-VI.2 General User Interface
+ +VI.2 General User Interface
+ 20.10 Provide a list of the titles and dates of all currently published items
+ 20.20 Provide a link to the archive of old news items
+ 20.30 Provide a one-item view of each news item, displaying it in its associated template format together with a link for comments
+ 20.40 Ensure that non 'text/html' news bodies are converted to HTML using Intermedia text filters -VI.3 Registered User Interface
+VI.3 Registered User Interface
+
+ 30.10 Same requirements as under 20.x.
+ 30.20 Provide a link to create a news item
+ 30.30 Ensure that the news application allows registered users to either enter text/html in a text area or to upload a complete file.
+ 30.40 Provide for various MIME types for uploaded items, including MS Word docs.
+ 30.50 Provide a display of those MIME types which are admissible for upload.
+ 30.60 Ensure that a news item shall be allowed to include an audio file (real player) for live reports.VI.4 Administrator Interface
+ 40.10 Same as under 30.x.
+ 40.20 Provide a link to the administrative pages
+ 40.30 Provide an administrative summary page of all news items
+ 40.40 Provide a switch to view either archived, live, or all items
+ 40.50 Provide a selection box with commands for collective adminstration
+ 40.60 Provide various archive functions on multiple items, like 'archive next day|week|month' for a set of selected items.
+ 40.70 Allow for the approve functions to operate on multiple items simultaneously
+ 40.80 Allow functions to move item(s) into different scopes (e.g. from private to public news)
+ 40.90 Provide an administrative page for each individual item with a list of revisions
+ 40.100 Provide a link to add a revision
+ 40.110 Ensure that clicking on a revision brings up the page as it would look to the public -40.120 Provide a view of unapproved items only.
VI.5 Template Administration
+40.120 Provide a view of unapproved items only.
+VI.5 Template Administration
+ 50.10 Provide a link to an administrative suite of templates
+ 50.10.10 Allow for the viewing/testing of templates through provided sample news items
+ 50.10.20 Upload template files
+ 50.10.30 Associate templates to news items
+ 50.10.40 Set default news templateVI.6 Additional Requirements
+ 60.10 Provide a subscriber link to sign up for notifications for when a new news item is posted. Ensure that notifications can be had at user-specifiable frequency: immediately, daily, weekly, montly, and quarterly.
+ 60.20 Provide a counter of how many times an item has been viewed
+ 60.30 Provide a display of the ranking of most seen items
+ 60.40 Provide a Yahoo-like 'Mail this news article to a Friend' link -
stefan\@arsdigita.com
Last modified: Tue Dec 12 14:15:00 2000 +
+stefan\@arsdigita.com +
+Last modified: Tue Dec 12 14:15:00 2000 --------------5759157623D344C3E04E6F78-- - Index: openacs-4/packages/oacs-dav/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/oacs-dav/www/doc/index.adp,v diff -u -N -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/oacs-dav/www/doc/index.adp 21 Aug 2015 10:28:48 -0000 1.1.2.2 +++ openacs-4/packages/oacs-dav/www/doc/index.adp 25 Aug 2015 18:02:22 -0000 1.1.2.3 @@ -2,22 +2,28 @@{/doc/oacs-dav {webDAV Support}} {OpenACS WebDAV Support} OpenACS WebDAV Support - - - OpenACS WebDAV Support
Introduction
This package implements a WebDAV interface to the OpenACS +
OpenACS WebDAV Support
+Introduction
+This package implements a WebDAV interface to the OpenACS Content Repository. In addition to generic access to content items, there is a service-contract interface so packages can define custom handlers for WebDAV methods for objects that belong to that -package.
Installation
Install through the APM. If you install file-storage, WebDAV +package.
+Installation
+Install through the APM. If you install file-storage, WebDAV support is installed automatically. In addtion you should check the tDAV specific configuration parameters to the AOLserver configuration file. The default parameters work fine, they will -create webdav URLs like yoursite/dav/*
You can visit the /webdav-support/ page to control webdav +create webdav URLs like yoursite/dav/*
+You can visit the /webdav-support/ page to control webdav access on a per-folder basis. Packages that support WebDAV will add folders to this list and an administrator can then activate or -deactivate the folders.
How it Works
OpenACS WebDAV Support requires the tDAV AOLserver module to +deactivate the folders.
+How it Works
+OpenACS WebDAV Support requires the tDAV AOLserver module to implement most of the WebDAV protocol. OpenACS WebDAV Support just -provides and interface between tDAV and the Content Repository
Each content_type that requires a custom handler much implement +provides and interface between tDAV and the Content Repository
+Each content_type that requires a custom handler much implement the
davservice contract. Each content type should implement thedavservice contract with the implementation name the same as the content_type. This includes @@ -30,35 +36,43 @@ packages to set the initial content_type for new items created through WebDAV. Each package should implement thedav_put_typeservice contract with the implementation -named the same as the package key.Each package instance that will allow WebDAV access should +named the same as the package key.
+Each package instance that will allow WebDAV access should register a package_id and folder_id for the root content_folder that corresponds with the URI of the package's mount point using -
oacs_dav::register_folder.Dispatching Requests
A preauth filter is registered for all WebDAV methods. This +
+oacs_dav::register_folder.Dispatching Requests
+A preauth filter is registered for all WebDAV methods. This calls oacs_dav::authorize which will set oacs_dav::conn user_id to the OpenACS user_id or 0 is the request is not authenticated. This filter also calls oacs_dav::setup_conn sets up the basic information needed to authorize the request. If authorization fails a 401 HTTP response is returned requesting authentication information. If authorization is successful the filter returns filter_ok and the tdav::filter* filter for the method is -called.
The tdav::filter* commands setup global information for each +called.
+The tdav::filter* commands setup global information for each method that is independent of the storage type. After this filter runs, the request is handled by the registered procedure for -OpenACS oacs_dav::handle_request.
oacs_dav::handle_request determines the package_id that should +OpenACS oacs_dav::handle_request.
+oacs_dav::handle_request determines the package_id that should handle the URI. This is based on the standard OpenACS site_node Tcl API. After the package is found, the root folder for that package is retreived from the dav_package_folder_map table. Using the folder_id, and the URI of the request, the
content_item__get_idpl/sql(plpgsql) procedure is called to find the item_id for the request. If no item_id is found and the requested method is PUT, a new item should be created. If -the method is not PUT, a 404 error should be returned.oacs_dav::handle_request will call the service contract +the method is not PUT, a 404 error should be returned.
+oacs_dav::handle_request will call the service contract implemenation for the content_type of the item. If the request is a PUT, first the dav_put_type service contract for the package_key of the request is called. For file-storage this returns "file_storage_object" so items created by PUT are created as -file_storage_objects instead of generic content_revisions.
The service contract implementation for each operation must +file_storage_objects instead of generic content_revisions.
+The service contract implementation for each operation must return the response data in the format required by tDAV. The documentation for the tdav::respond::* procedures named for each -method describe what is required.
Release Notes
Please file bugs in the Bug Tracker.
- +method describe what is required. +Release Notes
+Please file bugs in the Bug Tracker.
Index: openacs-4/packages/openacs-default-theme/www/resources/styles/default-master.css =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/openacs-default-theme/www/resources/styles/default-master.css,v diff -u -N -r1.14.4.1 -r1.14.4.2 --- openacs-4/packages/openacs-default-theme/www/resources/styles/default-master.css 25 Aug 2015 11:09:37 -0000 1.14.4.1 +++ openacs-4/packages/openacs-default-theme/www/resources/styles/default-master.css 25 Aug 2015 18:02:22 -0000 1.14.4.2 @@ -407,7 +407,7 @@ #content-wrapper { clear: both; border-top: 1px solid #fff; - padding-bottom: 75px; + /*padding-bottom: 10px;*/ } Index: openacs-4/packages/ref-countries/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/ref-countries/www/doc/index.adp,v diff -u -N -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/ref-countries/www/doc/index.adp 21 Aug 2015 10:28:48 -0000 1.1.2.2 +++ openacs-4/packages/ref-countries/www/doc/index.adp 25 Aug 2015 18:02:22 -0000 1.1.2.3 @@ -2,9 +2,10 @@{/doc/ref-countries {Reference Data - Country}} {Reference Country Documentation} Reference Country Documentation - - - Reference Country Documentation
This package provides standard country codes as defined in +
Reference Country Documentation
+
+This package provides standard country codes as defined in ISO-3166-1 -
Release Notes
Please file bugs in the Bug Tracker.
- + +Release Notes
+Please file bugs in the Bug Tracker.
Index: openacs-4/packages/rss-support/www/doc/bboard.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/rss-support/www/doc/bboard.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/rss-support/www/doc/bboard.adp 20 Aug 2015 17:47:49 -0000 1.1.2.1 +++ openacs-4/packages/rss-support/www/doc/bboard.adp 25 Aug 2015 18:02:22 -0000 1.1.2.2 @@ -2,11 +2,13 @@{/doc/rss-support {RSS Support}} {RSS Support: Bboard Sample Implementation} RSS Support: Bboard Sample Implementation - - Bboard Sample Implementation
+ by Andrew Grumet -Back to RSS SupportThe steps:
+ +Back to RSS Support +
+The steps:
+
- Install the rss-support package, and mount a single instance at a convenient location (e.g.
/rss). Note that rss-support is a service package and a singleton.- Create one or more implentations Of the RssGenerationSubscriber @@ -29,5 +31,6 @@ time of the last report built).
- Summaries can be found at
-/${RssGenOutputDirectory}/${ImplementationName}/${summary_context_id}/rss.xml
aegrumet\@alum.mit.edu - +
+aegrumet\@alum.mit.edu Index: openacs-4/packages/rss-support/www/doc/design.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/rss-support/www/doc/design.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/rss-support/www/doc/design.adp 20 Aug 2015 17:47:49 -0000 1.1.2.1 +++ openacs-4/packages/rss-support/www/doc/design.adp 25 Aug 2015 18:02:22 -0000 1.1.2.2 @@ -2,39 +2,49 @@{/doc/rss-support {RSS Support}} {RSS Support Design Notes} RSS Support Design Notes - - RSS Support Design Notes
-by Andrew Grumet, -Jerry Asher and -Dave BauerFrom the specification,
RDF Site Summary (RSS) is a lightweight + +by Andrew Grumet +, +Jerry Asher + and +Dave Bauer +From the specification,
+RDF Site Summary (RSS) is a lightweight multipurpose extensible metadata description and syndication format. RSS is an XML application, conforms to the W3C's RDF Specification and is extensible via XML-namespace and/or RDF based modularization.+ This service package provides low-level support for generating and parsing RSS feeds.1. Feed generation
+ Feed generation is the process of summarizing local content as RSS xml. To generate a feed we need to know+ The last item is included with an eye toward performance. In the event that a particular summary is expensive to produce, we may opt to rebuild at most every N minutes (or hours, or days). -
- the site context whose content is to be summarized,
- how to retrieve the various required and optional metadata fields
- whether any changes have been made since the last summary was built
- how often to rebuild the summary (if changes are present)
Usage scenarios
+
+Usage scenarios
+
- Publisher wishes to syndicate the Bar Forum in the Foo Bboard package instance.
- Luckily, the bboard package implements the summary service contract for individual forums.
- Programmer registers the context identifier for the Bar Forum with the summary service, indicating that the summary should be built no more than once per hour.
- Summary is available at /some/url/specific/to/bar/forum/summary.xml
-Service contract
The feed generation service contract is called +
Service contract
+The feed generation service contract is called
RssGenerationSubscriberand consists of two -operations.+operations. +
+
- -
Datasource(summary_context_id)returns a data structure that contains all required metadata fields plus @@ -45,28 +55,36 @@ timestamp that is used to determine if the live summary is out of date. The timestamp is given as the number of seconds since midnight on January 1, 1970, i.e. Unix time.Under the hood
+
Under the hood
+RSS files.All summaries are static files. They are served from a static directory under the webroot specific by the RssGenOutputDirectory, which defaults to
rss. The full -path to an RSS file is given by+path to an RSS file is given by +-Note: we assume that/${RssGenOutputDirectory}/${ImplementationName}/${summary_context_id}/rss.xml${ImplementationName}and -${summary_context_id}contain OS- and URL-friendly + +Note: we assume that${ImplementationName}+ and +${summary_context_id}+ contain OS- and URL-friendly characters.Subscription. A programmer registers a context with the summary service through API functions (we can make it possible -through web UI as well if that makes sense).
+through web UI as well if that makes sense).
+Summary context. A summary context is a content-containing domain which implements the summary service contract. A summary context is not identical to a package instance. For example, a single bboard package instance might contain 3 summary contexts, one for each of the forums in the instance. The summary context must, however, be an acs_object for permissioning purposes (create a shell acs_object if necessary). Only one -subscription is allowed per summary context.
+subscription is allowed per summary context.
+Service. A scheduled proc runs through all subscribed contexts, checking to see if the live summary is stale and also if the minimum "quiet time" has elapsed. If the conditions for rebuild @@ -76,8 +94,9 @@ used to dispatch different versions of the summary builder as well as to support extensibility via modules. Warning: This design expects the output of
Datasourceto be reasonably small, as we will have to -parse this list-of-lists to generate a summary.
+parse this list-of-lists to generate a summary. +
+ aegrumet\@alum.mit.edu, jerry\@theashergroup.com, dave\@thedesignexperience.org - Index: openacs-4/packages/rss-support/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/rss-support/www/doc/index.adp,v diff -u -N -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/rss-support/www/doc/index.adp 21 Aug 2015 10:28:49 -0000 1.1.2.2 +++ openacs-4/packages/rss-support/www/doc/index.adp 25 Aug 2015 18:02:22 -0000 1.1.2.3 @@ -2,19 +2,24 @@{/doc/rss-support {RSS Support}} {RSS Support} RSS Support - - RSS Support
-by Andrew Grumet, -Jerry Asher and -Dave Bauer+ +by Andrew Grumet +, +Jerry Asher + and +Dave Bauer +
+ +
- Design Notes
- Bboard Sample Implementation
- To-do's
-
- Exception handling
- Testing
- Port to Oracle
Release Notes
Please file bugs in the Bug Tracker.
Release Notes
+Please file bugs in the Bug Tracker.
+
+ aegrumet\@alum.mit.edu, jerry\@theashergroup.com, dave\@thedesignexperience.org - Index: openacs-4/packages/search/www/doc/guidelines.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/search/www/doc/guidelines.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/search/www/doc/guidelines.adp 20 Aug 2015 17:47:50 -0000 1.1.2.1 +++ openacs-4/packages/search/www/doc/guidelines.adp 25 Aug 2015 18:02:23 -0000 1.1.2.2 @@ -2,8 +2,7 @@{/doc/search {Search}} {How to make an object type searchable?} How to make an object type searchable? - - +Index: openacs-4/packages/search/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/search/www/doc/index.adp,v diff -u -N -r1.1.2.3 -r1.1.2.4 --- openacs-4/packages/search/www/doc/index.adp 21 Aug 2015 10:28:49 -0000 1.1.2.3 +++ openacs-4/packages/search/www/doc/index.adp 25 Aug 2015 18:02:23 -0000 1.1.2.4 @@ -2,10 +2,14 @@+How to make an object type searchable?
by Neophytos Demetriou (k2pts\@cytanet.com.cy)
@@ -143,4 +142,4 @@ -{/doc/search {Search}} {Search} Search - - - Search
OpenACS documentationRelease Notes
Please file bugs in the Bug Tracker.
Vinod -KurupLast modified: Fri Aug 21 12:14:30 CEST 2015 - - +Search
+OpenACS documentation + +
+Release Notes
+Please file bugs in the Bug Tracker.
+Vinod +Kurup +Last modified: Fri Aug 21 12:14:30 CEST 2015 + \ No newline at end of file Index: openacs-4/packages/tsearch2-driver/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/tsearch2-driver/www/doc/index.adp,v diff -u -N -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/tsearch2-driver/www/doc/index.adp 21 Aug 2015 10:28:49 -0000 1.1.2.2 +++ openacs-4/packages/tsearch2-driver/www/doc/index.adp 25 Aug 2015 18:02:23 -0000 1.1.2.3 @@ -4,17 +4,20 @@Tsearch2 Full-text Search Engine Driver for OpenACS 5.x - - - Tsearch2 Full-text Search Engine Driver for OpenACS 5.x
Tsearch2 Driver provides full-text searching of a PostgreSQL -database by using PostgreSQL's tsearch2 FtsEngineDriver
Requirements for this search implementation
+
+Tsearch2 Full-text Search Engine Driver for OpenACS 5.x
+Tsearch2 Driver provides full-text searching of a PostgreSQL +database by using PostgreSQL's tsearch2 FtsEngineDriver
+Requirements for this search implementation
+
- OpenACS 5.x
- PostgreSQL 7.3 or newer
- PostgreSQL's tsearch2 module installed. (Pg versions 7.3 and 7.4 require a patch and tsearch2.sql to be loaded into the database)
- This package installed
- search package to be mounted somewhere.
- FtsEngineDriver parameter of search package set to "tsearch2-driver".
- indexing some data
-+
Install OpenACS' Tsearch2 Full-Text Search -Package
+Package +
If you have not yet, install PostgreSQL's tsearch2 module.
Click
Adminon the top of the default home page. If prompted, log in with the account @@ -42,12 +45,15 @@- -
Restart AOLserver. Wait a minute, then click on
Main Siteat the top of the page.+ +
Enable Full Text Search in -packages
Weblogger (lars-blogger), ETP (edit-this-page), and a few other +packages +
Weblogger (lars-blogger), ETP (edit-this-page), and a few other packages have code to generate indexed content. We are using lars-blogger to illustrate how to enable Full Text Search in -packages.
+packages. +
Install the lars-blogger package, if it is not yet installed.
@@ -69,24 +75,35 @@ [$OPENACS_SERVICE_NAME postgresql]$
psql $OPENACS_SERVICE_NAME -f lars-blogger-sc-create.sql- -
Restart AOLserver.
Full Text Search should be enabled now, if not consult http://openacs.org/forums/message-view?message_id=154759. + +
Full Text Search should be enabled now, if not consult http://openacs.org/forums/message-view?message_id=154759. This link also contains some hints on how to make sure it is -enabled.
Indexing data
Once tsearch2-driver is installed, add some content to be -indexed.
Adding search indexing to packages
Standard coding practice is to put indexing code in +enabled.
+Indexing data
+Once tsearch2-driver is installed, add some content to be +indexed.
+Adding search indexing to packages
+Standard coding practice is to put indexing code in package-key/sql/postgresql/package-key-sc-create.sql. View these -examples for how to implement:
+examples for how to implement: +
+
- packages/edit-this-page/sql/postgresql/edit-this-page-sc-create.sql
- packages/lars-blogger/sql/postgresql/lars-blogger-sc-create.sql
-Indexing pre-existing content that has been indexed before
If your pre-existing content has been indexed before (e.g. +
Indexing pre-existing content that has been indexed before
+If your pre-existing content has been indexed before (e.g. because the search package was mounted before as part of a previous search service), you have to tell the search package to -reindex:
+reindex: ++insert into search_observer_queue ( select my_id, now(),'INSERT' from my_table ); -For forums and ETP this looks like:
++For forums and ETP this looks like:
+insert into search_observer_queue ( select message_id, now(), 'INSERT' from forums_messages ); @@ -95,9 +112,13 @@ select live_revision from cr_items where content_type = 'etp_page_revision' ) etp ); -Implementation notes
This version includes only the most basic features. Many options +
Implementation notes
+This version includes only the most basic features. Many options are possible by adding admin configurable parameters. The current service contract definitions are not flexible enough to work well with every possible search driver, so some features may require -making some improvements to the search package also.
Release Notes
Please file bugs in the Bug Tracker.
Dave Bauer dave\@thedesignexperience.org 2004-06-05
- +making some improvements to the search package also. +Release Notes
+Please file bugs in the Bug Tracker.
+Dave Bauer dave\@thedesignexperience.org 2004-06-05
