Part�III.�For OpenACS Package Developers

Prev		Next

Prev	Part�III.�For OpenACS Package Developers	Next

Add the Service to CVS - OPTIONAL.�These steps take an existing OpenACS directory and add it to a CVS repository.

Links

- + Linking falls into two different categories: inside the book you're making and outside:

1. Inside linking, cross-referencing other parts of your book

By having unique id's you can cross-reference any part of your book with a simple tag, regardless of where that part is. -

Check out how I link to a subsection of the Developer's Guide:

Put this in your XML:

+	  
Check out how I link to a subsection of the Developer's Guide:
Put this in your XML:
 - Find information about creating a package in
 <xref linkend="packages-making-a-package"></xref>.
 
And the output is:
@@ -206,7 +206,7 @@
 	    packages-looks, the
 	    parser will try its best to explain where the link takes you.

2. Linking outside the documentation

- + If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just a little different @@ -227,7 +227,7 @@ do it, so if you want to start converting your documents right away, start out with the ones without graphics ;)

- + To insert a graphic we use the elements <mediaobject>, <imageobject>, @@ -253,7 +253,7 @@ Put your graphics in a separate directory ("images") and link to them only with relative paths.

Lists

- + Here's how you make the DocBook equivalent of the three usual HTML-lists:

1. How to make an <ul>: Making an unordered list is pretty much like doing the same thing in HTML - if you close your <li>, that is. The only differences are that each list item has to be wrapped in something more, such as @@ -298,7 +298,7 @@ </variablelist>

Tables

- + DocBook supports several types of tables, but in most cases, the <informaltable> is enough: @@ -335,7 +335,7 @@ <table> for an example.

Emphasis

- + Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one - <emphasis>.

Index: openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html,v diff -u -r1.39 -r1.40 --- openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html 24 Jun 2004 10:44:39 -0000 1.39 +++ openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html 29 Jun 2004 15:50:15 -0000 1.40 @@ -59,7 +59,7 @@

Transition Rules

So what distinguishes an alpha release from a beta release? Or from a production release? We follow a specific set of rules for how OpenACS makes the transition from one state of maturity to -the next. These rules are fine-tuned with each release; an example is 5.0.0 Milestones and Milestone Criteria

Naming Database Upgrade Scripts

Database upgrade scripts must be named very precisely in order for the Package Manager to run the correct script at the correct time.

Upgrade scripts should be named /packages/myfirstpackage/sql/postgresql/upgrade/upgrade-OLDVERSION-NEWVERSION.sql
If the version you are working on is a later version than the current released version, OLDVERSION should be the current version. The current version is package version in the APM and in /packages/myfirstpackage/myfirstpackage.info. So if forums is at 2.0.1, OLDVERSION should be 2.0.1d1. Note that this means that new version development that includes an upgrade must start at d2, not d1. +the next. These rules are fine-tuned with each release; an example is 5.0.0 Milestones and Milestone Criteria

Naming Database Upgrade Scripts

Database upgrade scripts must be named very precisely in order for the Package Manager to run the correct script at the correct time.

Upgrade scripts should be named /packages/myfirstpackage/sql/postgresql/upgrade/upgrade-OLDVERSION-NEWVERSION.sql
If the version you are working on is a later version than the current released version, OLDVERSION should be the current version. The current version is package version in the APM and in /packages/myfirstpackage/myfirstpackage.info. So if forums is at 2.0.1, OLDVERSION should be 2.0.1d1. Note that this means that new version development that includes an upgrade must start at d2, not d1.
If you are working on a pre-release version of a package, use the current package version as OLDVERSION. Increment the package version as appropriate (see above) and use the new version as NEWVERSION. For example, if you are working on 2.0.1d3, make it 2.0.1d4 and use upgrade-2.0.1d3-2.0.1d4.sql.
Database upgrades should be confined to development releases, not alpha or beta releases.
Never use a final release number as a NEWVERSION. If you do, then it is impossible to add any more database upgrades without incrementing the overall package version.
Use only the d, a, and b letters in OLDVERSION and NEWVERSION. rc is not supported by OpenACS APM.
The distance from OLDVERSION to NEWVERSION should never span a release. For example if we had a bug fix in acs-kernel on 5.1.0 you wouldn't want a file upgrade-5.0.4-5.1.0d1.sql since if you subsequently need to provide a 5.0.4-5.0.5 upgrade you will have to rename the 5.0.4-5.1.0 upgrade since you can't have upgrades which overlap like that. Instead, use upgrade-5.1.0d1-5.1.0d2.sql Index: openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html,v diff -u -r1.28 -r1.29 --- openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html 24 Jun 2004 10:44:39 -0000 1.28 +++ openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html 29 Jun 2004 15:50:15 -0000 1.29 @@ -1,4 +1,4 @@ -External Authentication Requirements
Prev Chapter�15.�Kernel Documentation Next
External Authentication Requirements
Vision
People have plenty of usernames and passwords already, we +External Authentication Requirements
Prev Chapter�15.�Kernel Documentation Next
External Authentication Requirements
Vision
People have plenty of usernames and passwords already, we don't want them to have yet another. We want people to be able to log in to OpenACS with the same password they use to log in to any other system.
Besides, administrators have better things to do than create @@ -44,7 +44,7 @@ only one implementation of the authentication API, namly the one included in OpenACS Core.
Authentication Driver API: The service contract which authentication drivers implement.

Prev	Chapter�15.�Kernel Documentation	Next

Prev	Chapter�15.�Kernel Documentation	Next

Conceptual Pictures

Authentication:

Account Management (NO PICTURE YET)

Batch Synchronization (NO PICTURE YET)

Requirements

New API

Feature	Status	Description
EXT-AUTH-01	A	Extend Authentication/Acct Status API
EXT-AUTH-03	A	Account Creation API
EXT-AUTH-05	A	Password Management API
EXT-AUTH-30	A	Authority Management API

Login

Feature	Status	Description
EXT-AUTH-04	A	Rewrite login, register, and admin pages to use APIs
EXT-AUTH-38	A	ad_form complain feature
EXT-AUTH-19	A	Rewrite password recovery to use API
EXT-AUTH-21	A	Rewrite email verification with API
EXT-AUTH-28	A	Username is email switch

Users will log in using a username, a authority, and a +

Account Management (NO PICTURE YET)

Batch Synchronization (NO PICTURE YET)

Requirements

New API

Feature	Status	Description
EXT-AUTH-01	A	Extend Authentication/Acct Status API
EXT-AUTH-03	A	Account Creation API
EXT-AUTH-05	A	Password Management API
EXT-AUTH-30	A	Authority Management API

Login

Feature	Status	Description
EXT-AUTH-04	A	Rewrite login, register, and admin pages to use APIs
EXT-AUTH-38	A	ad_form complain feature
EXT-AUTH-19	A	Rewrite password recovery to use API
EXT-AUTH-21	A	Rewrite email verification with API
EXT-AUTH-28	A	Username is email switch

Users will log in using a username, a authority, and a password. The authority is the source for user/password verification. OpenACS can be an authority itself.

Each user in OpenACS will belong to exactly one authority, which can either be the "local" OpenACS users table, in which case the Index: openacs-4/packages/acs-core-docs/www/form-builder.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/form-builder.html,v diff -u -r1.18 -r1.19 --- openacs-4/packages/acs-core-docs/www/form-builder.html 24 Jun 2004 10:44:39 -0000 1.18 +++ openacs-4/packages/acs-core-docs/www/form-builder.html 29 Jun 2004 15:50:15 -0000 1.19 @@ -1,4 +1,4 @@ -Using HTML Forms

Prev	Chapter�11.�Development Reference	Next

Using HTML Forms

Overview

Multi-part Elements

Some elements have more than one choice, or can submit more than one value.

SELECT elements

Creating the form element.�Populate a list of lists with values for the option list.

set foo_options [db_list_of_lists foo_option_list "
+Using HTML FormsPrev Chapter�11.�Development Reference  Next
Using HTML Forms
Overview
Multi-part Elements
Some elements have more than one choice, or can submit more than one value.
SELECT elements
Creating the form element.�Populate a list of lists with values for the option list.
set foo_options [db_list_of_lists foo_option_list "
     select foo,
            foo_id
       from foos
@@ -43,5 +43,5 @@
     ns_set print $mypage
 }
     
Common Errors
Here are some common errors and what to do when you
-    encounter them:
Error when selecting values
This generally happens when there is an error in your
+    encounter them:
Error when selecting values
This generally happens when there is an error in your
           query.
($Id$)
Prev Home  Next
Programming with AOLserver Up  Chapter�12.�Engineering Standards
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/i18n-convert.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-convert.html,v
diff -u -r1.14 -r1.15
--- openacs-4/packages/acs-core-docs/www/i18n-convert.html	24 Jun 2004 10:44:39 -0000	1.14
+++ openacs-4/packages/acs-core-docs/www/i18n-convert.html	29 Jun 2004 15:50:15 -0000	1.15
@@ -71,7 +71,7 @@
         test. If you don't provide the package_key argument then all
         packages with catalog files will be checked. 
         The script will run its checks primarily on en_US xml catalog files.
-

Avoiding common i18n mistakes

Replace complicated keys with longer, simpler keys.�When writing in one language, it is possible to create clever code to make correct text. In English, for example, you can put an if command at the end of a word which adds "s" if a count is anything but 1. This pluralizes nouns correctly based on the data. However, it is confusing to read and, when internationalized, may result in message keys that are both confusing and impossible to set correctly in some languages. While internationalizing, watch out that the automate converter does not create such keys. Also, refactor compound text as you encounter it.
The automated system can easily get confused by tags within message texts, so that it tries to create two or three message keys for one long string with a tag in the middle. In these cases, uncheck those keys during the conversion and then edit the files directly. For example, this code:
```
  <p class="form-help-text"><b>Invitations</b> are sent,
+      
```

Avoiding common i18n mistakes

Replace complicated keys with longer, simpler keys.�When writing in one language, it is possible to create clever code to make correct text. In English, for example, you can put an if command at the end of a word which adds "s" if a count is anything but 1. This pluralizes nouns correctly based on the data. However, it is confusing to read and, when internationalized, may result in message keys that are both confusing and impossible to set correctly in some languages. While internationalizing, watch out that the automate converter does not create such keys. Also, refactor compound text as you encounter it.

The automated system can easily get confused by tags within message texts, so that it tries to create two or three message keys for one long string with a tag in the middle. In these cases, uncheck those keys during the conversion and then edit the files directly. For example, this code:

  <p class="form-help-text"><b>Invitations</b> are sent,
           when this wizard is completed and casting begins.</p>

has a bold tag which confuses the converter into thinking there are two message keys for the text beginning "Invitations ..." where there should be one:

Instead, we cancel those keys, edit the file manually, and put in a single temporary message tag:

  <p class="form-help-text"> <#Invitations_are_sent <b>Invitations</b> are sent, 
 when this wizard is completed and casting begins.#>
   </p>

Complex if statements may produce convoluted message keys that are very hard to localize. Rewrite these if statements. For example:

Select which case <if @simulation.casting_type@ eq "open">and
Index: openacs-4/packages/acs-core-docs/www/index.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/index.html,v
diff -u -r1.41 -r1.42
--- openacs-4/packages/acs-core-docs/www/index.html	24 Jun 2004 10:44:39 -0000	1.41
+++ openacs-4/packages/acs-core-docs/www/index.html	29 Jun 2004 15:50:15 -0000	1.42
@@ -1 +1 @@
-OpenACS Core Documentation  Next
OpenACS Core Documentation
Table of Contents
I. OpenACS For Everyone
1. High level information: What is OpenACS?
Overview
OpenACS Release Notes
II. Administrator's Guide
2. Installation Overview
Basic Steps
Prerequisite Software
3. Complete Installation
Install a Unix-like system and supporting software
Install Oracle 8.1.7
Install PostgreSQL
Install AOLserver 4
Install OpenACS 5.2.0d1
OpenACS Installation Guide for Windows2000
OpenACS Installation Guide for Mac OS X
4. Configuring a new OpenACS Site
How Do I?
5. Upgrading
Overview
Upgrading 4.5 or higher to 4.6.3
Upgrading OpenACS 4.6.3 to 5.0
Upgrading 5.0.0 to 5.0.x
Upgrading the OpenACS files
Upgrading Platform components
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
Running a PostgreSQL database on another server
Deleting a tablespace
Vacuum Postgres nightly
8. Backup and Recovery
Backup Strategy
Manual backup and recovery
Automated Backup
Using CVS for backup-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
Install nsopenssl
Install tclwebtest.
Install PHP for use in AOLserver
Install Squirrelmail for use as a webmail system for OpenACS
Install AOLserver 3.3oacs1
C. Credits
Where did this document come from?
Linux Install Guides
Security Information
Resources
III. For OpenACS Package Developers
9. Development Tutorial
Creating an Application Package
Setting Up Database Objects
Creating Web Pages
Debugging and Automated Testing
10. Advanced Topics
Write the Requirements and Design Specs
Add the new package to CVS
Adding Comments
Admin Pages
Categories
Profile your code
Prepare the package for distribution.
Notifications
Hierarchical data
Using .vuh files for pretty urls
Laying out a page with CSS instead of tables
Sending HTML email from your application
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
Using HTML Forms
12. Engineering Standards
OpenACS Style Guide
Release Version Numbering
Constraint naming standard
ACS File Naming and Formatting Standards
PL/SQL Standards
Variables
Automated Testing
13. Documentation Standards
OpenACS Documentation Guide
Using PSGML mode in Emacs
Using nXML mode in Emacs
Detailed Design Documentation Template
System/Application Requirements Template
14. Internationalization
Internationalization and Localization Overview
How Internationalization/Localization works in OpenACS
How to Internationalize a Package
Design Notes
Translator's Guide
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
OpenACS Core and .LRN
How to Update the OpenACS.org repository
How to package and release an OpenACS Package
How to Update the translations
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
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
11.1. Context Hierarchy Example
11.2. acs_objects example data
14.1. Internationalization and Localization Overview
List of Examples
12.1. Getting datetime from the database ANSI-style
  Next
  Part�I.�OpenACS For Everyone
docs@openacs.org
View comments on this page at openacs.org
+OpenACS Core Documentation  Next
OpenACS Core Documentation
Table of Contents
I. OpenACS For Everyone
1. High level information: What is OpenACS?
Overview
OpenACS Release Notes
II. Administrator's Guide
2. Installation Overview
Basic Steps
Prerequisite Software
3. Complete Installation
Install a Unix-like system and supporting software
Install Oracle 8.1.7
Install PostgreSQL
Install AOLserver 4
Install OpenACS 5.2.0d1
OpenACS Installation Guide for Windows2000
OpenACS Installation Guide for Mac OS X
4. Configuring a new OpenACS Site
How Do I?
5. Upgrading
Overview
Upgrading 4.5 or higher to 4.6.3
Upgrading OpenACS 4.6.3 to 5.0
Upgrading 5.0.0 to 5.0.x
Upgrading the OpenACS files
Upgrading Platform components
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
Running a PostgreSQL database on another server
Deleting a tablespace
Vacuum Postgres nightly
8. Backup and Recovery
Backup Strategy
Manual backup and recovery
Automated Backup
Using CVS for backup-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
Install nsopenssl
Install tclwebtest.
Install PHP for use in AOLserver
Install Squirrelmail for use as a webmail system for OpenACS
Install AOLserver 3.3oacs1
C. Credits
Where did this document come from?
Linux Install Guides
Security Information
Resources
III. For OpenACS Package Developers
9. Development Tutorial
Creating an Application Package
Setting Up Database Objects
Creating Web Pages
Debugging and Automated Testing
10. Advanced Topics
Write the Requirements and Design Specs
Add the new package to CVS
Adding Comments
Admin Pages
Categories
Profile your code
Prepare the package for distribution.
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
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
Using HTML Forms
12. Engineering Standards
OpenACS Style Guide
Release Version Numbering
Constraint naming standard
ACS File Naming and Formatting Standards
PL/SQL Standards
Variables
Automated Testing
13. Documentation Standards
OpenACS Documentation Guide
Using PSGML mode in Emacs
Using nXML mode in Emacs
Detailed Design Documentation Template
System/Application Requirements Template
14. Internationalization
Internationalization and Localization Overview
How Internationalization/Localization works in OpenACS
How to Internationalize a Package
Design Notes
Translator's Guide
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
OpenACS Core and .LRN
How to Update the OpenACS.org repository
How to package and release an OpenACS Package
How to Update the translations
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
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
11.1. Context Hierarchy Example
11.2. acs_objects example data
14.1. Internationalization and Localization Overview
List of Examples
12.1. Getting datetime from the database ANSI-style
  Next
  Part�I.�OpenACS For Everyone
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/objects.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/objects.html,v
diff -u -r1.40 -r1.41
--- openacs-4/packages/acs-core-docs/www/objects.html	24 Jun 2004 10:44:39 -0000	1.40
+++ openacs-4/packages/acs-core-docs/www/objects.html	29 Jun 2004 15:50:15 -0000	1.41
@@ -78,7 +78,7 @@
 Fire up your text editor and open the
 ROOT/packages/notes/sql/oracle/notes-create.sql (ROOT/packages/notes/sql/postgresql/notes-create.sql for the PG version) file created
 when we created the package.  Then, do the following:
-
Describe the new type to the type system

+
Describe the new type to the type system

 First, add an entry to the acs_object_types table with the following PL/SQL call:
 
 begin  
@@ -138,7 +138,7 @@
 because the new type note is a subtype of
 acs_object, it will inherit these attributes, so there is
 no need for us to define them.
-
Define a table in which to store your objects

+
Define a table in which to store your objects

 The next thing we do is make a small modification to the data model to
 reflect the fact that each row in the notes table
 represents something that is not only an object of type
@@ -163,7 +163,7 @@
 use the acs_objects table to find objects will
 transparently find any objects that are instances of any subtype of
 acs_objects.
-
Define a package for type specific procedures

+
Define a package for type specific procedures

 The next step is to define a PL/SQL package for your new type, and
 write some basic procedures to create and delete objects. Here is a
 package definition for our new type:
@@ -211,7 +211,7 @@
 object OBJ was "read only", then any other object that used OBJ as its
 context would also be "read only" by default. We'll talk about this more
 later.
-
Define a package body for type specific procedures

+
Define a package body for type specific procedures

 The PL/SQL package body contains the implementations of the procedures
 defined above. The only subtle thing going on here is that we must use
 acs_object.new to insert a row into
Index: openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html,v
diff -u -r1.33 -r1.34
--- openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html	24 Jun 2004 10:44:39 -0000	1.33
+++ openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html	29 Jun 2004 15:50:15 -0000	1.34
@@ -100,7 +100,7 @@
     
Context Hierarchy

       Suppose objects A, B, ..., 
       and F form the following hierarchy. 
-    
Table�11.1.�Context Hierarchy Example
A
+    
Table�11.1.�Context Hierarchy Example
A
   	        object_id=10
               
B
   	        object_id=20
@@ -116,7 +116,7 @@
       This can be represented in the 
       acs_objects table
       by the following entries: 
-    
Table�11.2.�acs_objects example data
object_id context_id
20 10
30 10
40 20
50 20
60 30

+    
Table�11.2.�acs_objects example data
object_id context_id
20 10
30 10
40 20
50 20
60 30

       The first entry tells us that object 20 is the descendant of object 10, and
       the third entry shows that object 40 is the descendant of object 20. By
       running a CONNECT BY query,
Index: openacs-4/packages/acs-core-docs/www/tutorial-advanced.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-advanced.html,v
diff -u -r1.25 -r1.26
--- openacs-4/packages/acs-core-docs/www/tutorial-advanced.html	24 Jun 2004 10:44:39 -0000	1.25
+++ openacs-4/packages/acs-core-docs/www/tutorial-advanced.html	29 Jun 2004 15:50:16 -0000	1.26
@@ -1,4 +1,4 @@
-Chapter�10.�Advanced Topics
Prev Part�III.�For OpenACS Package Developers  Next
Chapter�10.�Advanced Topics
Table of Contents
Write the Requirements and Design Specs
Add the new package to CVS
Adding Comments
Admin Pages
Categories
Profile your code
Prepare the package for distribution.
Notifications
Hierarchical data
Using .vuh files for pretty urls
Laying out a page with CSS instead of tables
Sending HTML email from your application
Future Topics
by Joel Aufrecht
+Chapter�10.�Advanced TopicsPrev Part�III.�For OpenACS Package Developers  Next
Chapter�10.�Advanced Topics
Table of Contents
Write the Requirements and Design Specs
Add the new package to CVS
Adding Comments
Admin Pages
Categories
Profile your code
Prepare the package for distribution.
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
Future Topics
by Joel Aufrecht
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
         
This tutorial covers topics which are not essential to
Index: openacs-4/packages/acs-core-docs/www/tutorial-caching.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-caching.html,v
diff -u
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/acs-core-docs/www/tutorial-caching.html	29 Jun 2004 15:50:16 -0000	1.1
@@ -0,0 +1,10 @@
+Basic Caching
Prev Chapter�10.�Advanced Topics  Next
Basic Caching
Based on a post by Dave Bauer.
+          OpenACS docs are written by the named authors, and may be edited
+          by OpenACS documentation staff.
+        
Implement your proc as my_proc_not_cached
Create a version of your proc called my_proc which wraps the non-cached version in the caching mechanism.  In this example, my_proc_not_cached takes one argument, -foo, so the wrapper passes that on.
ad_proc my_proc {-foo} {
+        Get a cached version of my_proc.
+} {
+    return [util_memoize my_proc_not_cached -foo $foo]
+}
In your code, always call my_proc.  There will be a seperate cache item for each unique call to my_proc_not_cached so that calls with different arguments are cached seperately. You can flush the cache for each cache key by calling util_memoize_flush my_proc_not_cached args.

+          The cached material will of course become obsolete over time.  There are two ways to handle this.
Timed Expiration: pass in max_age to util_memoize.  If the content is older than max_age, it will be re-generated.

+              Direct Flushing.  In any proc which invalidates the cached content, call  util_memoize_flush my_proc_not_cached args.
If you are correctly flushing the cached value, then it will need to be reloaded.  You may wish to pre-load it, so that the loading delay does not impact users.  If you have a sequence of pages, you could call the cached proc in advance, to increase the chances that it's loaded and current when the user reaches it.  Or, you can call (and discard) it immediately after flushing it.
Prev Home  Next
Sending HTML email from your application Up  Scheduled Procedures
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/tutorial-css-layout.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-css-layout.html,v
diff -u -r1.1 -r1.2
--- openacs-4/packages/acs-core-docs/www/tutorial-css-layout.html	24 Jun 2004 10:44:39 -0000	1.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-css-layout.html	29 Jun 2004 15:50:16 -0000	1.2
@@ -1,4 +1,4 @@
-Laying out a page with CSS instead of tablesPrev Chapter�10.�Advanced Topics  Next
Laying out a page with CSS instead of tables
.LRN home page with table-based layout
A sample of the HTML code (full source)
<table border="0" width="100%">
+Laying out a page with CSS instead of tablesPrev Chapter�10.�Advanced Topics  Next
Laying out a page with CSS instead of tables
.LRN home page with table-based layout
A sample of the HTML code (full source)
<table border="0" width="100%">
   <tr>
     <td valign="top" width="50%">
       <table class="element" border=0 cellpadding="0" cellspacing="0" width="100%">
@@ -20,7 +20,7 @@
                   <table border="0" bgcolor="white" cellpadding="0" cellspacing="0" width="100%">
                     <tr>
                       <td class=element-text>
-                        MBA 101
.LRN Home with CSS-based layout
A sample of the HTML code (full source)
<div class="left">
+                        MBA 101
.LRN Home with CSS-based layout
A sample of the HTML code (full source)
<div class="left">
   <div class="portlet-wrap-shadow">
     <div class="portlet-wrap-bl">
       <div class="portlet-wrap-tr">
Index: openacs-4/packages/acs-core-docs/www/tutorial-cvs.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-cvs.html,v
diff -u -r1.15 -r1.16
--- openacs-4/packages/acs-core-docs/www/tutorial-cvs.html	24 Jun 2004 10:44:39 -0000	1.15
+++ openacs-4/packages/acs-core-docs/www/tutorial-cvs.html	29 Jun 2004 15:50:16 -0000	1.16
@@ -58,4 +58,4 @@
 initial revision: 1.1
 done
 (many lines omitted)
-[$OPENACS_SERVICE_NAME myfirstpackage]$
Figure�10.1.�Upgrading a local CVS repository
Prev Home  Next
Write the Requirements and Design Specs Up  Adding Comments
docs@openacs.org
View comments on this page at openacs.org
+[$OPENACS_SERVICE_NAME myfirstpackage]$
Figure�10.1.�Upgrading a local CVS repository
Prev Home  Next
Write the Requirements and Design Specs Up  Adding Comments
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/tutorial-distribute.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-distribute.html,v
diff -u -r1.15 -r1.16
--- openacs-4/packages/acs-core-docs/www/tutorial-distribute.html	24 Jun 2004 10:44:39 -0000	1.15
+++ openacs-4/packages/acs-core-docs/www/tutorial-distribute.html	29 Jun 2004 15:50:16 -0000	1.16
@@ -6,5 +6,5 @@
         (37.1KB)
         after the label Distribution
         File: and save the file to
-        /tmp.

+        /tmp.

 
Prev Home  Next
Profile your code Up  Notifications
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/tutorial-future-topics.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-future-topics.html,v
diff -u -r1.7 -r1.8
--- openacs-4/packages/acs-core-docs/www/tutorial-future-topics.html	24 Jun 2004 09:42:26 -0000	1.7
+++ openacs-4/packages/acs-core-docs/www/tutorial-future-topics.html	29 Jun 2004 15:50:16 -0000	1.8
@@ -1,6 +1,6 @@
-Future TopicsPrev Chapter�10.�Advanced Topics  Next
Future Topics
How to enforce security so that users can't
+Future Topics
Prev Chapter�10.�Advanced Topics  Next
Future Topics
How to enforce security so that users can't
       change other users records
How to use the content management tables so that
       ... what?
How to change the default stylesheets for Form
       Builder HTML forms.
How to make your package searchable with OpenFTS/Oracle
How to prepare pagelets for inclusion in other pages
How and when to put procedures in a tcl procedure library
More on ad_form - data validation, other stuff.
-      (plan to draw from Jon Griffin's doc)
How and when to implement caching
partialquery in xql
How to use the html/text entry widget to get the
-      "does this look right" confirm page 
APM package dependencies
See also the OpenACS Programming FAQ
Prev Home  Next
Sending HTML email from your application Up  Chapter�11.�Development Reference
docs@openacs.org
View comments on this page at openacs.org
+      (plan to draw from Jon Griffin's doc)
partialquery in xql
How to use the html/text entry widget to get the
+      "does this look right" confirm page 
APM package dependencies
See also the OpenACS Programming FAQ
Prev Home  Next
Scheduled Procedures Up  Chapter�11.�Development Reference
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/tutorial-schedule-procs.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-schedule-procs.html,v
diff -u
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/acs-core-docs/www/tutorial-schedule-procs.html	29 Jun 2004 15:50:16 -0000	1.1
@@ -0,0 +1,6 @@
+Scheduled ProceduresPrev Chapter�10.�Advanced Topics  Next
Scheduled Procedures
Put this proc in a file /packages/myfirstpackage/tcl/scheduled-init.tcl.  Files in /tcl with the -init.tcl ending are sourced on server startup.  This one executes my_proc every 60 seconds:
ad_schedule_proc 60 myfirstpackage::my_proc
+
This executes once a day, at midnight:
ad_schedule_proc \
+    -schedule_proc ns_schedule_daily \
+    [list 0 0] \
+    myfirstpackage::my_proc
+
See ad_schedule_proc for more information.
Prev Home  Next
Basic Caching Up  Future Topics
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/variables.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/variables.html,v
diff -u -r1.18 -r1.19
--- openacs-4/packages/acs-core-docs/www/variables.html	24 Jun 2004 10:44:40 -0000	1.18
+++ openacs-4/packages/acs-core-docs/www/variables.html	29 Jun 2004 15:50:16 -0000	1.19
@@ -3,7 +3,7 @@
           by OpenACS documentation staff.
         
Date and Time Variables
Starting with OpenACS 5.0 and the introduction of acs-lang,
     we recommend retrieving date/time information from the database in
-    ANSI format and then using lc_time_fmt to format it for display.
Example�12.1.�Getting datetime from the database ANSI-style
db_multirow -extend { mydate_pretty } {
+    ANSI format and then using lc_time_fmt to format it for display.
Example�12.1.�Getting datetime from the database ANSI-style
db_multirow -extend { mydate_pretty } {
     select to_char(mydate, 'YYYY-MM-DD HH24:MI:SS') as mydate_ansi,
           ...
     ...
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml,v
diff -u -r1.30 -r1.31
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml	24 Jun 2004 10:44:41 -0000	1.30
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml	29 Jun 2004 15:50:18 -0000	1.31
@@ -973,6 +973,61 @@
     
   
 
+  
+    Basic Caching
+    
+      Based on a post by Dave Bauer.
+    
+    
+      
+        Implement your proc as my_proc_not_cached
+      
+      
+        Create a version of your proc called my_proc which wraps the non-cached version in the caching mechanism.  In this example, my_proc_not_cached takes one argument, -foo, so the wrapper passes that on.
+        ad_proc my_proc {-foo} {
+        Get a cached version of my_proc.
+} {
+    return [util_memoize my_proc_not_cached -foo $foo]
+}
+      
+      
+        In your code, always call my_proc.  There will be a seperate cache item for each unique call to my_proc_not_cached so that calls with different arguments are cached seperately. You can flush the cache for each cache key by calling util_memoize_flush my_proc_not_cached args.
+      
+      
+        
+          The cached material will of course become obsolete over time.  There are two ways to handle this. 
+
+        
+          
+            Timed Expiration: pass in max_age to util_memoize.  If the content is older than max_age, it will be re-generated.
+          
+          
+            
+              Direct Flushing.  In any proc which invalidates the cached content, call  util_memoize_flush my_proc_not_cached args.
+          
+        
+      
+      
+        If you are correctly flushing the cached value, then it will need to be reloaded.  You may wish to pre-load it, so that the loading delay does not impact users.  If you have a sequence of pages, you could call the cached proc in advance, to increase the chances that it's loaded and current when the user reaches it.  Or, you can call (and discard) it immediately after flushing it.
+      
+    
+  
+  
+    Scheduled Procedures
+    Put this proc in a file /packages/myfirstpackage/tcl/scheduled-init.tcl.  Files in /tcl with the -init.tcl ending are sourced on server startup.  This one executes my_proc every 60 seconds:
+    ad_schedule_proc 60 myfirstpackage::my_proc
+
+This executes once a day, at midnight:
+    ad_schedule_proc \
+    -schedule_proc ns_schedule_daily \
+    [list 0 0] \
+    myfirstpackage::my_proc
+
+    See ad_schedule_proc for more information.
+  
+
+
+
   
   Future Topics
     
@@ -988,7 +1043,6 @@
       How and when to put procedures in a tcl procedure library
       More on ad_form - data validation, other stuff.
       (plan to draw from Jon Griffin's doc)
-      How and when to implement caching
       partialquery in xql
       How to use the html/text entry widget to get the
       "does this look right" confirm page

Prev	Home	Next
Programming with AOLserver	Up	Chapter�12.�Engineering Standards

For OpenACS Package Developers

Appendix�D.�Using CVS with an OpenACS Site

Headlines, Sections

Code

Links

Lists

Tables

Emphasis

Transition Rules

Naming Database Upgrade Scripts

Naming Database Upgrade Scripts

External Authentication Requirements

Vision

External Authentication Requirements

Vision

Conceptual Pictures

Requirements

New API

Login

Requirements

New API

Login

Using HTML Forms

Overview

Multi-part Elements

SELECT elements

Using HTML Forms

Overview

Multi-part Elements

SELECT elements

Common Errors

Error when selecting values

Error when selecting values

Avoiding common i18n mistakes

Avoiding common i18n mistakes

OpenACS Core Documentation

OpenACS Core Documentation

Describe the new type to the type system

Describe the new type to the type system

Define a table in which to store your objects

Define a table in which to store your objects

Define a package for type specific procedures

Define a package for type specific procedures

Define a package body for type specific procedures

Define a package body for type specific procedures

Context Hierarchy

Chapter�10.�Advanced Topics

Chapter�10.�Advanced Topics

Basic Caching

Laying out a page with CSS instead of tables

.LRN home page with table-based layout

Laying out a page with CSS instead of tables

.LRN home page with table-based layout

.LRN Home with CSS-based layout

.LRN Home with CSS-based layout

Future Topics

Future Topics

Scheduled Procedures

Date and Time Variables