As root, untar - aolserver3.3ad13-oacs1-beta-src.tar.gz + aolserver3.3oacs1.tar.gz into /usr/local/src.
[root@yourserver root]# cd /usr/local/src -[root@yourserver src]# tar xzf /tmp/aolserver3.3ad13-oacs1-beta-src.tar.gz +[root@yourserver src]# tar xzf /tmp/aolserver3.3oacs1.tar.gz [root@yourserver src]#
cd /usr/local/src -tar xzf /tmp/aolserver3.3ad13-oacs1-beta-src.tar.gz
Compile and install AOLserver. First, prepare the installation directory and the source code. The message about BUILD-MODULES can be ignored.
root@yourserver root]# mkdir -p /usr/local/aolserver +tar xzf /tmp/aolserver3.3oacs1.tar.gz
Compile and install AOLserver. First, prepare the installation directory and the source code. The message about BUILD-MODULES can be ignored.
root@yourserver root]# mkdir -p /usr/local/aolserver [root@yourserver root]# cd /usr/local/src/aolserver [root@yourserver aolserver]# ./conf-clean cat: BUILD-MODULES: No such file or directory Done. [root@yourserver aolserver]#
mkdir -p /usr/local/aolserver cd /usr/local/src/aolserver ./conf-clean
- Put the name of the driver(s) that you want into - conf-db. This can be - postgresql, - oracle, or the word + If you are using Oracle, edit + conf-db and change + postgresql to + oracle, or to the word both if you want both drivers installed. -
[root@yourserver aolserver]# echo "postgresql" > conf-db -[root@yourserver aolserver]#
conf-inst should contain the - location where AOLserver is to be installed. This defaults to - /usr/local/aolserver, so we - don't need to change it.
conf-make should contain the +
conf-inst should contain the + location where AOLserver is to be installed. Overwrite the + tarball's default value with our default value, /usr/local/aolserver:
[root@yourserver aolserver]# echo "/usr/local/aolserver" > conf-inst +[root@yourserver aolserver]#
conf-make should contain the name of the GNU Make command on your system. It defaults to gmake. Verify that gmake is installed:
[root@yourserver aolserver]# gmake -v GNU Make version 3.79.1, by Richard Stallman and Roland McGrath. @@ -45,14 +44,8 @@ Report bugs to <bug-make@gnu.org>. -[root@yourserver aolserver]#
If you don't get similar results, including an equal or higher version number to 3.79.1, install gmake or check your aliases.
- If you're going to be installing the Postgresql driver, you'll - have to adjust the makefile first. This will hopefully be cleaned - up in future versions of this distribution. -
[root@yourserver aolserver]# emacs pgdriver/makefile
- Edit the lines containing PGLIB and PGINC so they look like this: -
PGLIB=/usr/local/pgsql/lib -PGINC=/usr/local/pgsql/include
Run the conf program, which compiles AOLserver and the default modules and installs them.
[root@yourserver aolserver]# ./conf +[root@yourserver aolserver]#
If you don't get similar results, including an equal or higher version number to 3.79.1, install gmake or check your aliases.
Set an environment variable that the nspostgres driver + Makefile needs to compile correctly and run conf, which compiles AOLserver and the default modules and installs them.
[root@yourserver aolserver]# export POSTGRES=/usr/local/pgsql; ./conf Building in /usr/local/aolserver with the following modules: aolserver @@ -69,7 +62,7 @@ Running gmake in nsrewrite/; output in log/nsrewrite.log Running gmake in nssha1/; output in log/nssha1.log Running gmake in nsxml/; output in log/nsxml.log -Running gmake in pgdriver/; output in log/pgdriver.log +Running gmake in nspostgres/; output in log/nspostgres.log Creating ... ================================================================== Done Building Sat Mar 8 10:31:35 PST 2003 Index: openacs-4/packages/acs-core-docs/www/apm-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/apm-design.html,v diff -u -r1.6.2.3 -r1.6.2.4 --- openacs-4/packages/acs-core-docs/www/apm-design.html 30 Mar 2003 06:04:04 -0000 1.6.2.3 +++ openacs-4/packages/acs-core-docs/www/apm-design.html 7 Apr 2003 16:59:25 -0000 1.6.2.4 @@ -1,5 +1,5 @@ -
OpenACS 4.6.2 Package Manager Design +
OpenACS 4.6.2 Package Manager Design An installation of the OpenACS includes the OpenACS Kernel, some services that extend the kernel's functionality, and some applications intended for end-users. Packages function as individual pieces of subsites. A subsite can contain multiple @@ -89,7 +89,7 @@ packages for other ACS users to download and install.
For a simple illustration of the difference between ACS without APM (pre-3.3) and ACS with APM (3.3 and beyond), consider a hypothetical ACS installation that uses only two of the thirty-odd modules available circa ACS -3.2 (say, bboard and e-commerce):
[D]APM itself is part of a package, the OpenACS Kernel, an OpenACS +3.2 (say, bboard and e-commerce):
[D]APM itself is part of a package, the OpenACS Kernel, an OpenACS service that is the only mandatory component of an OpenACS installation.
The OpenACS is a platform for web-based application software, and any software platform has the potential to develop problems like those described above. Fortunately, there are many precedents for systematic solutions, Index: openacs-4/packages/acs-core-docs/www/apm-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/apm-requirements.html,v diff -u -r1.6.2.3 -r1.6.2.4 --- openacs-4/packages/acs-core-docs/www/apm-requirements.html 30 Mar 2003 06:04:04 -0000 1.6.2.3 +++ openacs-4/packages/acs-core-docs/www/apm-requirements.html 7 Apr 2003 16:59:25 -0000 1.6.2.4 @@ -1,5 +1,5 @@ -
OpenACS 4.6.2 Package Manager Requirements +
OpenACS 4.6.2 Package Manager Requirements On a test service, make sure that your backup-recovery process work. After backing up the database and file system, delete the service as detailed below and then recover it.
[root@yourserver root]# svc -d /service/service0 +[service0@yourserver service0]$
On a test service, make sure that your backup-recovery process work. After backing up the database and file system, delete the service as detailed below and then recover it.
[root@yourserver root]# svc -d /service/service0 [root@yourserver root]# mv /web/service0/ /web/service0.lost [root@yourserver root]# rm /service/service0 rm: remove symbolic link `/service/service0'? y Index: openacs-4/packages/acs-core-docs/www/bootstrap-acs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/bootstrap-acs.html,v diff -u -r1.8.2.3 -r1.8.2.4 --- openacs-4/packages/acs-core-docs/www/bootstrap-acs.html 30 Mar 2003 06:04:04 -0000 1.8.2.3 +++ openacs-4/packages/acs-core-docs/www/bootstrap-acs.html 7 Apr 2003 16:59:25 -0000 1.8.2.4 @@ -1,5 +1,5 @@ -
Bootstrapping OpenACS +
Bootstrapping OpenACS by Jon Salz
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff. Index: openacs-4/packages/acs-core-docs/www/db-api-detailed.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/db-api-detailed.html,v diff -u -r1.8.2.3 -r1.8.2.4 --- openacs-4/packages/acs-core-docs/www/db-api-detailed.html 30 Mar 2003 06:04:04 -0000 1.8.2.3 +++ openacs-4/packages/acs-core-docs/www/db-api-detailed.html 7 Apr 2003 16:59:25 -0000 1.8.2.4 @@ -1,5 +1,5 @@ -Database Access API +
Database Access API by Jon Salz. Revised and expanded by Roberto Mello (rmello at fslc dot usu dot edu), July 2002.
Index: openacs-4/packages/acs-core-docs/www/db-api.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/db-api.html,v diff -u -r1.8.2.3 -r1.8.2.4 --- openacs-4/packages/acs-core-docs/www/db-api.html 30 Mar 2003 06:04:04 -0000 1.8.2.3 +++ openacs-4/packages/acs-core-docs/www/db-api.html 7 Apr 2003 16:59:25 -0000 1.8.2.4 @@ -1,5 +1,5 @@ -The OpenACS Database Access API +
The OpenACS Database Access API By Pete Su and Jon Salz. Modified by Roberto Mello. Index: openacs-4/packages/acs-core-docs/www/docbook-primer.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/docbook-primer.html,v diff -u -r1.8.2.4 -r1.8.2.5 --- openacs-4/packages/acs-core-docs/www/docbook-primer.html 30 Mar 2003 06:04:04 -0000 1.8.2.4 +++ openacs-4/packages/acs-core-docs/www/docbook-primer.html 7 Apr 2003 16:59:25 -0000 1.8.2.5 @@ -1,5 +1,5 @@ -
OpenACS Documentation Guide +
OpenACS Documentation Guide By claus@arsdigita.com, with additions by Roberto Mello and the OpenACS Community @@ -32,7 +32,7 @@ In order to separate content and presentation, all OpenACS documentation will be marked up to conform to the DocBook XML DTD - + This enables us to publish in a variety of formats and relieves each contributor of the burden of presentation, freeing him to focus on content and sharing knowledge. @@ -53,7 +53,7 @@ list of elements and use more exotic features in your documents. The list is made up of SGML-elements but basically the same elements are valid in the XML DTD as long as you remember to: - +
Always close your tags with corresponding end-tags and to not use other tag minimization @@ -99,7 +99,7 @@ The documentation for each package will make up a little "book" that is structured like this - examples are emphasized: - +
book : Docs for one package - templating @@ -123,20 +123,20 @@ sources of these DocBook documents to get an idea of how they are tied together.
- + Given that your job starts at the sect1-level, all your documents should open with a <sect1>-tag and end with the corresponding </sect1>.
- + You need to feed every <sect1> two attributes. The first attribute, id, is standard and can be used with all elements. It comes in very handy when interlinking between documents (more about this when talking about links in the section called “Links”). The value of id has to be unique throughout the book you're making since the id's in your sect1's will turn into filenames when the book is parsed into HTML.
- + The other attribute is xreflabel. The value of this is the text that will appear as the link when referring to this sect1.
@@ -151,7 +151,7 @@ </sect1>
- + Inside this container your document will be split up into <sect2>'s, each with the same requirements - id and xreflabel @@ -160,7 +160,7 @@ When it comes to naming your sect2's and below, prefix them with some abbreviation of the id in the sect1 such as requirements-overview.
- + For displaying a snippet of code, a filename or anything else you just want to appear as a part of a sentence, we will use the tag <computeroutput>. @@ -170,12 +170,12 @@ <programlisting> is used. Just wrap your code block in it; mono-spacing, indents and all that stuff is taken care of automatically.
- + 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:
+
Check out how I link to a subsection of the Developer's Guide:
Put this in your XML: @@ -213,7 +213,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 @@ -234,7 +234,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>, @@ -260,7 +260,7 @@ Put your graphics in a separate directory ("images") and link to them only with relative paths.
- + 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 @@ -305,7 +305,7 @@ </variablelist>
- + DocBook supports several types of tables, but in most cases, the <informaltable> is enough: @@ -342,7 +342,7 @@ <table> for an example.
- + Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one - <emphasis>.
@@ -421,4 +421,4 @@
8/3/2002 Vinod Kurup 0.3 Added OpenACS information, updated tools, added extra links and added info to the Publishing section. - 12/24/2001 Roberto Mello 0.2 Changed recommendation from <phrase> to <emphasis role="strong"> 01/19/2000 Claus Rasmussen 0.1 Creation 12/2000 Claus Rasmussen View comments on this page at openacs.org +12/24/2001 Roberto Mello 0.2 Changed recommendation from <phrase> to <emphasis role="strong"> 01/19/2000 Claus Rasmussen 0.1 Creation 12/2000 Claus Rasmussen View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html,v diff -u -r1.8.2.3 -r1.8.2.4 --- openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html 30 Mar 2003 06:04:04 -0000 1.8.2.3 +++ openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html 7 Apr 2003 16:59:25 -0000 1.8.2.4 @@ -1,5 +1,5 @@ -Constraint naming standard
+Constraint naming standard Index: openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html,v diff -u -r1.8.2.3 -r1.8.2.4 --- openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html 30 Mar 2003 06:04:04 -0000 1.8.2.3 +++ openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html 7 Apr 2003 16:59:25 -0000 1.8.2.4 @@ -1,5 +1,5 @@ -
ACS File Naming and Formatting Standards By michael@arsdigita.com and +
ACS File Naming and Formatting Standards By michael@arsdigita.com and aure@arsdigita.com
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff. Index: openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html,v diff -u -r1.8.2.3 -r1.8.2.4 --- openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html 30 Mar 2003 06:04:04 -0000 1.8.2.3 +++ openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html 7 Apr 2003 16:59:25 -0000 1.8.2.4 @@ -1,5 +1,5 @@ -PL/SQL Standards ($Id$)View comments on this page at openacs.org 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.8.2.3 -r1.8.2.4 --- openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html 30 Mar 2003 06:04:04 -0000 1.8.2.3 +++ openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html 7 Apr 2003 16:59:25 -0000 1.8.2.4 @@ -1,5 +1,5 @@ -Release Version Numbering
+Release Version Numbering Index: openacs-4/packages/acs-core-docs/www/eng-standards.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards.html,v diff -u -r1.6.2.3 -r1.6.2.4 --- openacs-4/packages/acs-core-docs/www/eng-standards.html 30 Mar 2003 06:04:04 -0000 1.6.2.3 +++ openacs-4/packages/acs-core-docs/www/eng-standards.html 7 Apr 2003 16:59:25 -0000 1.6.2.4 @@ -1,2 +1,2 @@ -
Chapter 9. Engineering Standards View comments on this page at openacs.org +Chapter 10. Engineering Standards View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/filename.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/filename.html,v diff -u -r1.8.2.3 -r1.8.2.4 --- openacs-4/packages/acs-core-docs/www/filename.html 30 Mar 2003 06:04:04 -0000 1.8.2.3 +++ openacs-4/packages/acs-core-docs/www/filename.html 7 Apr 2003 16:59:25 -0000 1.8.2.4 @@ -1,5 +1,5 @@ -Detailed Design Documentation Template By You
+
Detailed Design Documentation Template By You
NOTE: Some of the sections of this template may not apply to your package, e.g. there may be no user-visible UI elements for a component of the OpenACS Core. Furthermore, it may be easier in some circumstances Index: openacs-4/packages/acs-core-docs/www/groups-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-design.html,v diff -u -r1.6.2.3 -r1.6.2.4 --- openacs-4/packages/acs-core-docs/www/groups-design.html 30 Mar 2003 06:04:04 -0000 1.6.2.3 +++ openacs-4/packages/acs-core-docs/www/groups-design.html 7 Apr 2003 16:59:25 -0000 1.6.2.4 @@ -1,5 +1,5 @@ -
OpenACS 4 Groups Design +
OpenACS 4 Groups Design by Rafael H. Schloming and Mark Thomas
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff. Index: openacs-4/packages/acs-core-docs/www/groups-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-requirements.html,v diff -u -r1.6.2.3 -r1.6.2.4 --- openacs-4/packages/acs-core-docs/www/groups-requirements.html 30 Mar 2003 06:04:04 -0000 1.6.2.3 +++ openacs-4/packages/acs-core-docs/www/groups-requirements.html 7 Apr 2003 16:59:25 -0000 1.6.2.4 @@ -1,5 +1,5 @@ -OpenACS 4 Groups Requirements +
OpenACS 4 Groups Requirements by Rafael H. Schloming, Mark Thomas
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff. 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 -r1.7.2.1 -r1.7.2.2 --- openacs-4/packages/acs-core-docs/www/index.adp 20 Dec 2002 04:42:24 -0000 1.7.2.1 +++ openacs-4/packages/acs-core-docs/www/index.adp 7 Apr 2003 16:59:25 -0000 1.7.2.2 @@ -27,22 +27,19 @@- For Everyone - - OpenACS 4.6 Release Notes - - Older Release Notes - -For OpenACS-admins +
Getting Started + - OpenACS 4.6.2 Release Notes + - Required Software - Unix Installation Guide - - Windows Installation Guide - -For Developers - - Kernel Documentation - - Developers Guide - - Engineering Standards + - Windows Installation Guide + - Mac OS X Installation Guide + - Developer Tutorial - API Browser for this OpenACS instance - - Other Developer Resources +Full Table of Contents + Primers and References + - AOLserver Documentation (the Tcl Developer's Guide in particular.) - Tcl for Web Nerds 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.6.2.4 -r1.6.2.5 --- openacs-4/packages/acs-core-docs/www/index.html 30 Mar 2003 20:33:12 -0000 1.6.2.4 +++ openacs-4/packages/acs-core-docs/www/index.html 7 Apr 2003 16:59:25 -0000 1.6.2.5 @@ -1,2 +1,2 @@ -
OpenACS Documentation Table of Contents
- I. OpenACS For Everyone
- II. Administrator's Guide
- III. For OpenACS Developers
- 8. Development Tutorial
- 9. Development Reference
- OpenACS 4.6.2 Packages
- OpenACS 4.6.2 Data Models and the Object System
- The Request Processor
- The OpenACS Database Access API
- Using Templates in OpenACS 4.6.2
- Groups, Context, Permissions
- Writing OpenACS 4.6.2 Application Pages
- Parties in OpenACS 4.6.2
- OpenACS 4.x Permissions Tediously Explained
- Object Identity
- Programming with AOLserver
- 10. Engineering Standards
- 11. Kernel Documentation
- Overview
- OpenACS 4 Object Model Requirements
- OpenACS 4 Object Model Design
- OpenACS 4 Permissions Requirements
- OpenACS 4 Permissions Design
- OpenACS 4 Groups Requirements
- OpenACS 4 Groups Design
- OpenACS 4 Subsites Requirements
- OpenACS 4 Subsites Design Document
- OpenACS 4.6.2 Package Manager Requirements
- OpenACS 4.6.2 Package Manager Design
- Database Access API
- OpenACS 4 Security Requirements
- OpenACS 4 Security Design
- OpenACS 4 Security Notes
- OpenACS 4 Request Processor Requirements
- OpenACS 4 Request Processor Design
- Documenting Tcl Files: Page Contracts and Libraries
- Bootstrapping OpenACS
List of Figures
View comments on this page at openacs.org +OpenACS Documentation Table of Contents
- I. OpenACS For Everyone
- II. Administrator's Guide
- III. For OpenACS Developers
- 8. Development Tutorial
- 9. Development Reference
- OpenACS 4.6.2 Packages
- OpenACS 4.6.2 Data Models and the Object System
- The Request Processor
- The OpenACS Database Access API
- Using Templates in OpenACS 4.6.2
- Groups, Context, Permissions
- Writing OpenACS 4.6.2 Application Pages
- Parties in OpenACS 4.6.2
- OpenACS 4.x Permissions Tediously Explained
- Object Identity
- Programming with AOLserver
- 10. Engineering Standards
- 11. Kernel Documentation
- Overview
- OpenACS 4 Object Model Requirements
- OpenACS 4 Object Model Design
- OpenACS 4 Permissions Requirements
- OpenACS 4 Permissions Design
- OpenACS 4 Groups Requirements
- OpenACS 4 Groups Design
- OpenACS 4 Subsites Requirements
- OpenACS 4 Subsites Design Document
- OpenACS 4.6.2 Package Manager Requirements
- OpenACS 4.6.2 Package Manager Design
- Database Access API
- OpenACS 4 Security Requirements
- OpenACS 4 Security Design
- OpenACS 4 Security Notes
- OpenACS 4 Request Processor Requirements
- OpenACS 4 Request Processor Design
- Documenting Tcl Files: Page Contracts and Libraries
- Bootstrapping OpenACS
List of Figures
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/individual-programs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/individual-programs.html,v diff -u -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/acs-core-docs/www/individual-programs.html 30 Mar 2003 06:04:04 -0000 1.1.2.2 +++ openacs-4/packages/acs-core-docs/www/individual-programs.html 7 Apr 2003 16:59:25 -0000 1.1.2.3 @@ -39,7 +39,7 @@ database, sends out HTTP responses, and logs requests and errors. OpenACS uses AOLserver; some people have had success running Apache with mod_nsd - see this - post.AOLserver 3.3ad13-oacs1-beta, REQUIRED.�Mat Kovach's source distribution of AOLserver, including all of the patches listed below.
+ post.
AOLserver 3.3oacs1, REQUIRED.�Mat Kovach's source distribution of AOLserver, including all of the patches listed below.
Mat Kovach is graciously maintaining an AOLserver distribution that includes all the patches and modules needed to run OpenACS 4.6.2. These instructions will describe how to install using his source Index: openacs-4/packages/acs-core-docs/www/install-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-overview.html,v diff -u -r1.7.2.3 -r1.7.2.4 --- openacs-4/packages/acs-core-docs/www/install-overview.html 30 Mar 2003 06:04:04 -0000 1.7.2.3 +++ openacs-4/packages/acs-core-docs/www/install-overview.html 7 Apr 2003 16:59:25 -0000 1.7.2.4 @@ -74,7 +74,7 @@ The basic steps to getting OpenACS up and running are:
Install an OS
Install a webserver (AOLServer)
Install a database (Oracle or PostgreSQL)
Install a database driver (allows the webserver to talk to the database) -
Start the OpenACS installer, which will configure a database instance..
This is text you will see on +
Start the OpenACS installer, which will configure a database instance..
This is text you will see on screen, such as a or link in a radio button list or menu.
This is text that you will type.
This is text from a program or file which you may need to examine or edit:
if {$database == "oracle"} { Index: openacs-4/packages/acs-core-docs/www/install-redhat.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-redhat.html,v diff -u -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/acs-core-docs/www/install-redhat.html 30 Mar 2003 06:04:04 -0000 1.1.2.2 +++ openacs-4/packages/acs-core-docs/www/install-redhat.html 7 Apr 2003 16:59:25 -0000 1.1.2.3 @@ -11,7 +11,7 @@ software (see the section called “Individual Programs” for details):libxml2
tcl
gmake and the compile and build environment.
and these optional items
emacs
cvs
ImageMagick
DocBook and supporting software
(In my experience, it's almost always a net time savings of several hours to install a new machine from scratch compared to installing each of these packages installed independently.)
Unplug the network cable from your computer. We don't want to connect to the network until we're sure the computer is secure. - + (Wherever you see the word secure, you should always read it as, "secure enough for our purposes, given the amount of work we're @@ -39,7 +39,7 @@ Review (and modify if needed) the partitions created and click
On the pop-up window asking "Are you sure you want to do this?" click - IF YOU ARE WIPING YOUR HARD DRIVE.
Click on the boot loader screen
Click on the boot loader screen
Configure Networking. Again, if you know what you're doing, do this step yourself, being sure to note the firewall holes. Otherwise, follow the instructions in this step to set up a computer directly connected to the internet with a dedicated IP address.
DHCP is a system by which a computer that @@ -60,7 +60,7 @@ Mail (SMTP). In the Other ports box, enter 443, 8000, 8443. Click . -Port 443 is for https (http over ssl), and 8000 and 8443 are http and https access to the development server we'll be setting up.
Select any additional languages you want the +Port 443 is for https (http over ssl), and 8000 and 8443 are http and https access to the development server we'll be setting up.
Select any additional languages you want the computer to support and then click
Choose your time zone and click .
Type in a root password, twice. To @@ -81,9 +81,9 @@ risk that's still screened by the firewall, or a resource hog. Just don't install a database or web server, because that would conflict with the database and web server we'll install later. -
check�Editors�(this�installs�emacs),
+check�Editors�(this�installs�emacs),
click�Details�next�to�Text-based�Internet,�check�lynx,�and�click�;
-check�Authoring�and�Publishing�(this�installs�docbook),
+check�Authoring�and�Publishing�(this�installs�docbook),
uncheck�Server�Configuration�Tools,
uncheck�Web�Server,
uncheck�Windows�File�Server,
@@ -96,7 +96,7 @@ Flat View and wait. In a minute, a list of packages will appear.uncheck�apmd�(monitors�power,�not�very�useful�for�servers),�
-check�ImageMagick�(required�for�the�photo-album�packages,�
+check�ImageMagick�(required�for�the�photo-album�packages,�
uncheckisdn4k-utils�(unless�you�are�using�isdn,�this�installs�a�useless�daemon),�
check�mutt�(a�mail�program�that�reads�Maildir),
uncheck�nfs-utils�(nfs�is�a�major�security�risk),�
@@ -124,7 +124,7 @@After it finishes rebooting and shows the login prompt, log in:
yourserver login: root Password: -[root@yourserver root]#
Lock down SSH
Lock down SSH
SSH is the protocol we use to connect securely to the computer (replacing telnet, which is insecure). sshd is the daemon that listens for incoming Index: openacs-4/packages/acs-core-docs/www/kernel-doc.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/kernel-doc.html,v diff -u -r1.6.2.3 -r1.6.2.4 --- openacs-4/packages/acs-core-docs/www/kernel-doc.html 30 Mar 2003 06:04:04 -0000 1.6.2.3 +++ openacs-4/packages/acs-core-docs/www/kernel-doc.html 7 Apr 2003 16:59:25 -0000 1.6.2.4 @@ -1,2 +1,2 @@ -
Chapter 10. Kernel Documentation Table of Contents
- Overview
- OpenACS 4 Object Model Requirements
- OpenACS 4 Object Model Design
- OpenACS 4 Permissions Requirements
- OpenACS 4 Permissions Design
- OpenACS 4 Groups Requirements
- OpenACS 4 Groups Design
- OpenACS 4 Subsites Requirements
- OpenACS 4 Subsites Design Document
- OpenACS 4.6.2 Package Manager Requirements
- OpenACS 4.6.2 Package Manager Design
- Database Access API
- OpenACS 4 Security Requirements
- OpenACS 4 Security Design
- OpenACS 4 Security Notes
- OpenACS 4 Request Processor Requirements
- OpenACS 4 Request Processor Design
- Documenting Tcl Files: Page Contracts and Libraries
- Bootstrapping OpenACS
View comments on this page at openacs.org +Chapter 11. Kernel Documentation Table of Contents
- Overview
- OpenACS 4 Object Model Requirements
- OpenACS 4 Object Model Design
- OpenACS 4 Permissions Requirements
- OpenACS 4 Permissions Design
- OpenACS 4 Groups Requirements
- OpenACS 4 Groups Design
- OpenACS 4 Subsites Requirements
- OpenACS 4 Subsites Design Document
- OpenACS 4.6.2 Package Manager Requirements
- OpenACS 4.6.2 Package Manager Design
- Database Access API
- OpenACS 4 Security Requirements
- OpenACS 4 Security Design
- OpenACS 4 Security Notes
- OpenACS 4 Request Processor Requirements
- OpenACS 4 Request Processor Design
- Documenting Tcl Files: Page Contracts and Libraries
- Bootstrapping OpenACS
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/kernel-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/kernel-overview.html,v diff -u -r1.3.2.3 -r1.3.2.4 --- openacs-4/packages/acs-core-docs/www/kernel-overview.html 30 Mar 2003 06:04:04 -0000 1.3.2.3 +++ openacs-4/packages/acs-core-docs/www/kernel-overview.html 7 Apr 2003 16:59:25 -0000 1.3.2.4 @@ -1,5 +1,5 @@ -Overview +
Overview Compared to its predecessors, version 4.6.2 of OpenACS has a much more structured organization, i.e. the most significant change is found at the system architecture level, @@ -28,4 +28,4 @@ This document provides a high level overview of the kernel package. Documentation for the other packages can be found elsewhere. -
View comments on this page at openacs.org +View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/linux-installation.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/linux-installation.html,v diff -u -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/acs-core-docs/www/linux-installation.html 30 Mar 2003 06:04:04 -0000 1.1.2.2 +++ openacs-4/packages/acs-core-docs/www/linux-installation.html 7 Apr 2003 16:59:25 -0000 1.1.2.3 @@ -3,7 +3,7 @@ by Joel Aufrecht
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff. -
Figure 3.1. Assumptions in this section
Fully qualified domain name of your server yourserver.test name of administrative access account remadmin OpenACS service service0 OpenACS service account service0 OpenACS database name service0 Root of OpenACS service file tree /web/service0 Location of source code tarballs for new software /tmp The OpenACS tarball contains some files which + Figure 3.1. Assumptions in this section
None of these locations are set in stone - they're simply @@ -26,12 +26,12 @@ files, unpack the tarball now.
[root@yourserver root]# cd /tmp [root@yourserver tmp]# tar xzf openacs-4-6.tgz
cd /tmp -tar xzf openacs-4-6.tgz
CVS is a source control system. Create and prepare a directory for a local cvs repository.
[root@yourserver tmp]# mkdir /cvsroot [root@yourserver tmp]# cvs -d /cvsroot init [root@yourserver tmp]#
mkdir /cvsroot -cvs -d /cvsroot init
If you plan to write or edit any documentation with emacs, install a customized emacs configuration file with DocBook commands in the skeleton directory, so it will be used for all new users. The file also @@ -42,7 +42,7 @@ installed in /package. These commands install daemontools and svgroup. svgroup is a script for granting permissions, to allow users other than root to use daemontools for specific - services.
Install Daemontools
Red Hat
Make sure you have the source tarball in + services.
Install Daemontools
Red Hat
Make sure you have the source tarball in /tmp, or download it. (The -p flag in mkdir causes all implied directories in the path to be made as well.)
[root@yourserver root]# mkdir -p /package @@ -71,7 +71,7 @@ control daemontools services.[root@yourserver root]# cp /tmp/openacs-4-6/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup [root@yourserver root]# chmod 755 /usr/local/bin/svgroup
cp /tmp/openacs-4-6/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup -chmod 755 /usr/local/bin/svgroup
Qmail is a Mail Transfer Agent. It handles incoming and outgoing mail. Install qmail if you want your OpenACS server to send and receive mail, and you don't want to use an alternate MTA.
Install ucspi.�This program handles incoming tcp connections.
[root@yourserver root]# cd /usr/local/src +chmod 755 /usr/local/bin/svgroup
Qmail is a Mail Transfer Agent. It handles incoming and outgoing mail. Install qmail if you want your OpenACS server to send and receive mail, and you don't want to use an alternate MTA.
Install ucspi.�This program handles incoming tcp connections.
[root@yourserver root]# cd /usr/local/src [root@yourserver src]# tar xzf /tmp/ucspi-tcp-0.88.tar.gz [root@yourserver src]# cd ucspi-tcp-0.88 [root@yourserver ucspi-tcp-0.88]# make @@ -93,7 +93,7 @@ tcpserver: usage: tcpserver [ -1UXpPhHrRoOdDqQv ] [ -c limit ] [ -x rules.cdb ] [ -B banner ] [ -g gid ] [ -u uid ] [ -b backlog ] [ -l localname ] [ -t timeout ] host port program [root@yourserver ucspi-tcp-0.88]# -
(I'm not sure if this next step is 100% necessary, but when I skip it I get problems. If you get the error 553 sorry, that domain isn't in my list of allowed rcpthosts (#5.7.1) then you need to do this.) AOLServer sends outgoing mail via the ns_sendmail command, which pipes a command to the sendmail executable. Or, in our @@ -107,7 +107,7 @@ send outgoing mail.
[root@yourserver ucspi-tcp-0.88]# cp /tmp/openacs-4-6/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp [root@yourserver ucspi-tcp-0.88]# tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp
cp /tmp/openacs-4-6/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp -tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp
First, set up the standard supporting users and build the binaries:
[root@yourserver root]# cd /usr/local/src +tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp
First, set up the standard supporting users and build the binaries:
[root@yourserver root]# cd /usr/local/src [root@yourserver src]# tar xzf /tmp/qmail-1.03.tar.gz [root@yourserver src]# mkdir /var/qmail [root@yourserver src]# groupadd nofiles @@ -140,7 +140,7 @@ useradd -g qmail -d /var/qmail qmailr useradd -g qmail -d /var/qmail qmails cd qmail-1.03 -make setup check
Replace sendmail with qmail's wrapper.
[root@yourserver qmail-1.03]# rm -f /usr/bin/sendmail +make setup check
Replace sendmail with qmail's wrapper.
[root@yourserver qmail-1.03]# rm -f /usr/bin/sendmail [root@yourserver qmail-1.03]# ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail [root@yourserver qmail-1.03]#
rm -f /usr/bin/sendmail @@ -162,7 +162,7 @@
cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root chmod 644 ~alias/.qmail* /var/qmail/bin/maildirmake ~alias/Maildir/ -chown -R alias.nofiles /var/qmail/alias/Maildir
Configure qmail to use the Maildir delivery format +chown -R alias.nofiles /var/qmail/alias/Maildir
Configure qmail to use the Maildir delivery format (instead of mbox), and install a version of the qmail startup script modified to use Maildir.
[root@yourserver alias]# echo "./Maildir" > /var/qmail/bin/.qmail [root@yourserver alias]# cp /tmp/openacs-4-6/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc [root@yourserver alias]# chmod 755 /var/qmail/rc Index: openacs-4/packages/acs-core-docs/www/object-identity.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-identity.html,v diff -u -r1.8.2.3 -r1.8.2.4 --- openacs-4/packages/acs-core-docs/www/object-identity.html 30 Mar 2003 06:04:04 -0000 1.8.2.3 +++ openacs-4/packages/acs-core-docs/www/object-identity.html 7 Apr 2003 16:59:25 -0000 1.8.2.4 @@ -1,5 +1,5 @@ -
Object Identity +
Object Identity by Rafael H. Schloming
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff. Index: openacs-4/packages/acs-core-docs/www/object-system-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-design.html,v diff -u -r1.6.2.3 -r1.6.2.4 --- openacs-4/packages/acs-core-docs/www/object-system-design.html 30 Mar 2003 06:04:04 -0000 1.6.2.3 +++ openacs-4/packages/acs-core-docs/www/object-system-design.html 7 Apr 2003 16:59:25 -0000 1.6.2.4 @@ -1,5 +1,5 @@ -OpenACS 4 Object Model Design +
OpenACS 4 Object Model Design by Pete Su, Michael Yoon, Richard Li Index: openacs-4/packages/acs-core-docs/www/object-system-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-requirements.html,v diff -u -r1.6.2.3 -r1.6.2.4 --- openacs-4/packages/acs-core-docs/www/object-system-requirements.html 30 Mar 2003 06:04:04 -0000 1.6.2.3 +++ openacs-4/packages/acs-core-docs/www/object-system-requirements.html 7 Apr 2003 16:59:25 -0000 1.6.2.4 @@ -1,5 +1,5 @@ -
OpenACS 4 Object Model Requirements +
OpenACS 4 Object Model Requirements By Pete Su
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff. 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.8.2.3 -r1.8.2.4 --- openacs-4/packages/acs-core-docs/www/objects.html 30 Mar 2003 06:04:04 -0000 1.8.2.3 +++ openacs-4/packages/acs-core-docs/www/objects.html 7 Apr 2003 16:59:25 -0000 1.8.2.4 @@ -1,5 +1,5 @@ -OpenACS 4.6.2 Data Models and the Object System +
OpenACS 4.6.2 Data Models and the Object System This is a very good time to back the service, even if it's not a production service. Making a backup now lets you roll back to this initial, clean setup at any point in the future, without repeating the install process. A full OpenACS service backup includes everything in the /web/service0/ directory. At this point it's probably sufficient to back up just the database, because you can recover the files from a tarball.
Note that, if you did the CVS options in this document, the /web/service0/etc directory is not included in cvs and you may want to add it.
PostGreSQL.�Create a backup file and verify that it was created and has a reasonable size (several megabytes).
[service0@yourserver service0]$ mkdir /web/service0/database-backup [service0@yourserver service0]$ pg_dump -f /web/service0/database-backup/initial_backup.dmp service0 [service0@yourserver service0]$ ls -al /web/service0/database-backup total 1425 @@ -525,7 +525,7 @@ [service0@yourserver service0]$
mkdir /web/service0/database-backup pg_dump -f /web/service0/database-backup/initial_backup.dmp service0 -ls -al /web/service0/database-backup
Oracle - INCOMPLETE.�
Backup can encompass all files in /web/service0. For a development server, putting the files in cvs is sufficient. (It's important then to back up the cvs repository!)
A quick way to automate database backup is a cron job. This is not recommended for production and is not part of the Reference Platform, because it is not cross-platform and can fail silently. More thorough methods are documented in the section called “Backup Strategy”
[service0@yourserver service0]$ export EDITOR=emacs;crontab -e
Add this line to the file. The numbers and stars at the beginning are cron columns that specify when the program should be run - in this case, whenever the minute is 0 and the hour is 1, i.e., 1:00 am every day.
0 1 * * * /usr/local/pgsql/bin/pg_dump -f /web/service0/database-backup/service0_$(date +%Y-%m-%d).dmp service0
If you plan to back up the whole /web/service0 directory, then it would be redundant to keep a history of database backups. In that case, set up the cron job to overwrite the previous backup each time:
0 1 * * * /usr/local/pgsql/bin/pg_dump -f /web/service0/database-backup/service0_nightly.dmp service0
Backup can encompass all files in /web/service0. For a development server, putting the files in cvs is sufficient. (It's important then to back up the cvs repository!)
A quick way to automate database backup is a cron job. This is not recommended for production and is not part of the Reference Platform, because it is not cross-platform and can fail silently. More thorough methods are documented in the section called “Backup Strategy”
[service0@yourserver service0]$ export EDITOR=emacs;crontab -e
Add this line to the file. The numbers and stars at the beginning are cron columns that specify when the program should be run - in this case, whenever the minute is 0 and the hour is 1, i.e., 1:00 am every day.
0 1 * * * /usr/local/pgsql/bin/pg_dump -f /web/service0/database-backup/service0_$(date +%Y-%m-%d).dmp service0
If you plan to back up the whole /web/service0 directory, then it would be redundant to keep a history of database backups. In that case, set up the cron job to overwrite the previous backup each time:
0 1 * * * /usr/local/pgsql/bin/pg_dump -f /web/service0/database-backup/service0_nightly.dmp service0
Analog is a program with processes webserver access logs, performs DNS lookup, and outputs HTML reports. Analog should already be installed. A modified configuration file is included in @@ -556,4 +556,4 @@ [root@yourserver root]# emacs /etc/cron.daily/analog
Put this into the file:
#!/bin/sh -/usr/share/analog-5.31/analog -G -g/web/service0/etc/analog.cfg[root@yourserver root]# chmod 755 /etc/cron.daily/analog
Test it by running the script.
[root@yourserver root]# sh /etc/cron.daily/analog
Browse to http://yourserver.test/log/traffic.html
Test your backup and recovery procedure.
Follow the instruction on the home page to change the appearance of your service or add more packages.
Proceed to the tutorial to learn how to develop your own packages.
($Id$)View comments on this page at openacs.org +/usr/share/analog-5.31/analog -G -g/web/service0/etc/analog.cfg[root@yourserver root]# chmod 755 /etc/cron.daily/analog
Test it by running the script.
[root@yourserver root]# sh /etc/cron.daily/analog
Browse to http://yourserver.test/log/traffic.html
Test your backup and recovery procedure.
Follow the instruction on the home page to change the appearance of your service or add more packages.
Proceed to the tutorial to learn how to develop your own packages.
($Id$)View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/packages.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/packages.html,v diff -u -r1.8.2.3 -r1.8.2.4 --- openacs-4/packages/acs-core-docs/www/packages.html 30 Mar 2003 06:04:04 -0000 1.8.2.3 +++ openacs-4/packages/acs-core-docs/www/packages.html 7 Apr 2003 16:59:25 -0000 1.8.2.4 @@ -1,5 +1,5 @@ -OpenACS 4.6.2 Packages View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/parties.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/parties.html,v diff -u -r1.8.2.3 -r1.8.2.4 --- openacs-4/packages/acs-core-docs/www/parties.html 30 Mar 2003 06:04:04 -0000 1.8.2.3 +++ openacs-4/packages/acs-core-docs/www/parties.html 7 Apr 2003 16:59:25 -0000 1.8.2.4 @@ -1,5 +1,5 @@ -Parties in OpenACS 4.6.2 +
Parties in OpenACS 4.6.2 by Rafael H. Schloming
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff. Index: openacs-4/packages/acs-core-docs/www/permissions-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-design.html,v diff -u -r1.6.2.3 -r1.6.2.4 --- openacs-4/packages/acs-core-docs/www/permissions-design.html 30 Mar 2003 06:04:04 -0000 1.6.2.3 +++ openacs-4/packages/acs-core-docs/www/permissions-design.html 7 Apr 2003 16:59:26 -0000 1.6.2.4 @@ -1,5 +1,5 @@ -OpenACS 4 Permissions Design +
OpenACS 4 Permissions Design by John Prevost and Rafael H. Schloming
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff. Index: openacs-4/packages/acs-core-docs/www/permissions-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-requirements.html,v diff -u -r1.6.2.3 -r1.6.2.4 --- openacs-4/packages/acs-core-docs/www/permissions-requirements.html 30 Mar 2003 06:04:04 -0000 1.6.2.3 +++ openacs-4/packages/acs-core-docs/www/permissions-requirements.html 7 Apr 2003 16:59:26 -0000 1.6.2.4 @@ -1,5 +1,5 @@ -OpenACS 4 Permissions Requirements +
OpenACS 4 Permissions Requirements by John McClary Prevost
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff. 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.1.2.4 -r1.1.2.5 --- openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html 30 Mar 2003 06:04:04 -0000 1.1.2.4 +++ openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html 7 Apr 2003 16:59:26 -0000 1.1.2.5 @@ -1,5 +1,5 @@ -OpenACS 4.x Permissions Tediously Explained +
OpenACS 4.x Permissions Tediously Explained by Vadim Nasardinov. Modified and converted to Docbook XML by Roberto Mello
The general permissions system has a relatively complex data model in OpenACS 4.x. @@ -86,7 +86,7 @@ to store permission information explicitly about every object, i.e. if the system has 100,000 and 1,000 users who have the read privilege on all objects, then we would need to store 100,000,000 entries of the form: -
Table 8.1.
object_id grantee_id privilege object_id_1 user_id_1 'read' object_id_1 user_id_2 'read' ... object_id_1 user_id_n 'read' object_id_2 user_id_1 'read' object_id_2 user_id_2 'read' ... object_id_2 user_id_n 'read' ... ... object_id_m user_id_1 'read' object_id_m user_id_2 'read' ... object_id_m user_id_n 'read' +
Table 9.1.
object_id grantee_id privilege object_id_1 user_id_1 'read' object_id_1 user_id_2 'read' ... object_id_1 user_id_n 'read' object_id_2 user_id_1 'read' object_id_2 user_id_2 'read' ... object_id_2 user_id_n 'read' ... ... object_id_m user_id_1 'read' object_id_m user_id_2 'read' ... object_id_m user_id_n 'read' Although quite feasible, this approach fails to take advantage of the fact that objects in the system are commonly organized hierarchally, and permissions usually follow the hierarchical structure, so that if user @@ -101,7 +101,7 @@
Suppose objects A, B, ..., and F form the following hierarchy. -
Table 8.2.
A +
Table 9.2.
A object_id=10
B object_id=20 @@ -117,23 +117,23 @@ This can be represented in the acs_objects table by the following entries: -
Table 8.3.
object_id context_id 20 10 30 10 40 20 50 20 60 30 +
Table 9.3.
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, we can compute that object 40 is the second-generation descendant of object 10. With this in mind, if we want to record the fact that user Joe has the read privilege on objects A, ..., F, we only need to record one entry in the acs_permissions table. -
Table 8.4.
object grantee privilege A Joe read +
Table 9.4.
object grantee privilege A Joe read The fact that Joe can also read B, C, ..., and F can be derived by ascertaining that these objects are children of A by traversing the context hierarchy. As it turns out, hierarchical queries are expensive. As Rafael Schloming put it so aptly, Oracle can't deal with hierarchies for shit.
One way to solve this problem is to cache a flattened view of the context tree like so: -
Table 8.5.
object ancestor n_generations A A 0 B B 0 B A 1 C C 0 C A 1 D D 0 D B 1 D A 2 E E 0 E B 1 E A 2 F F 0 F C 1 F A 2 +
Table 9.5.
object ancestor n_generations A A 0 B B 0 B A 1 C C 0 C A 1 D D 0 D B 1 D A 2 E E 0 E B 1 E A 2 F F 0 F C 1 F A 2 Note that the number of entries in the flattened view grows exponentially with respect to the depth of the context tree. For instance, if you have a fully populated binary tree with a depth of n, then the number of entries @@ -204,7 +204,7 @@ an object's security_inherit_p column to 'f', you can stop permissions from cascading down the context tree. In the following example, Joe does not have the read permissions on C and F. -
Table 8.6.
+Table 9.6.
A
object_id=10
readable�by�Joe
@@ -232,7 +232,7 @@ Privileges are also organized hierarchically. In addition to the five main system privileges defined in the ACS Kernel data model, application developers may define their own. For instance, the Bboard package defines the following privileges: -Table 8.7.
privilege create_category create_forum create_message delete_category delete_forum delete_message moderate_forum read_category read_forum read_message write_category write_forum write_message +
Table 9.7.
privilege create_category create_forum create_message delete_category delete_forum delete_message moderate_forum read_category read_forum read_message write_category write_forum write_message By defining parent-child relationship between privileges, the OpenACS data model makes it easier for developers to manage permissions. Instead of granting a user explicit read, write, delete, @@ -241,7 +241,7 @@ privilege to which the first four privileges are tied. To give a more detailed example, the Bboard privileges are structured as follows. -
Table 8.8.
admin create delete read write moderate forum create category create forum create message delete category delete forum delete message read category read forum read message write category write forum write message +
Table 9.8.
admin create delete read write moderate forum create category create forum create message delete category delete forum delete message read category read forum read message write category write forum write message The parent-child relationship between privileges is represented in the acs_privilege_hierarchy table:
@@ -287,7 +287,7 @@Now for the third hierarchy playing a promiment role in the permission system. The party data model is set up as follows. -
+
create table parties ( party_id not null @@ -371,7 +371,7 @@The acs_rels table entries would look like so: -
Table 8.10.
rel_type object_one object_two + Table 9.10.
rel_type object_one object_two membership_rel Pranksters @@ -406,7 +406,7 @@ The relevant entries in the acs_rels look like so. -
Table 8.11.
rel_type object_one object_two + Table 9.11.
rel_type object_one object_two composition_rel Pranksters @@ -617,7 +617,7 @@ Note that in the above example, acs_permissions had only one entry that needed to be deleted: -
Table 8.12.
object_id grantee_id privilege + Table 9.12.
object_id grantee_id privilege default_context registered_users Index: openacs-4/packages/acs-core-docs/www/permissions.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions.html,v diff -u -r1.8.2.3 -r1.8.2.4 --- openacs-4/packages/acs-core-docs/www/permissions.html 30 Mar 2003 06:04:04 -0000 1.8.2.3 +++ openacs-4/packages/acs-core-docs/www/permissions.html 7 Apr 2003 16:59:26 -0000 1.8.2.4 @@ -1,5 +1,5 @@ - Groups, Context, Permissions By Pete Su
+Groups, Context, Permissions Index: openacs-4/packages/acs-core-docs/www/postgres.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/postgres.html,v diff -u -r1.6.2.3 -r1.6.2.4 --- openacs-4/packages/acs-core-docs/www/postgres.html 30 Mar 2003 06:04:04 -0000 1.6.2.3 +++ openacs-4/packages/acs-core-docs/www/postgres.html 7 Apr 2003 16:59:26 -0000 1.6.2.4 @@ -42,7 +42,7 @@ Change to the postgres user and run ./configure to set the compilation options automatically. This is the point at which you can configure PostgreSQL in various ways. For example, if you want to enable - Unicode support, add the flags --enable-locale and --enable-multibyte. If you want to see what the other possibilities are, run ./configure --help. + Unicode support, add the flags --enable-locale and --enable-multibyte. If you want to see what the other possibilities are, run ./configure --help.
[root@yourserver src]# su - postgres [postgres@yourserver pgsql]$ cd /usr/local/src/postgresql-7.2.3 [postgres@yourserver postgresql-7.2.3]$ ./configure Index: openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html,v diff -u -r1.8.2.3 -r1.8.2.4 --- openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html 30 Mar 2003 06:04:04 -0000 1.8.2.3 +++ openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html 7 Apr 2003 16:59:26 -0000 1.8.2.4 @@ -1,5 +1,5 @@ -
Programming with AOLserver View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/psgml-mode.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/psgml-mode.html,v diff -u -r1.8.2.3 -r1.8.2.4 --- openacs-4/packages/acs-core-docs/www/psgml-mode.html 30 Mar 2003 06:04:04 -0000 1.8.2.3 +++ openacs-4/packages/acs-core-docs/www/psgml-mode.html 7 Apr 2003 16:59:26 -0000 1.8.2.4 @@ -1,5 +1,5 @@ -Using PSGML mode in Emacs +
Using PSGML mode in Emacs By David Lutterkort
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff. Index: openacs-4/packages/acs-core-docs/www/request-processor.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/request-processor.html,v diff -u -r1.8.2.3 -r1.8.2.4 --- openacs-4/packages/acs-core-docs/www/request-processor.html 30 Mar 2003 06:04:04 -0000 1.8.2.3 +++ openacs-4/packages/acs-core-docs/www/request-processor.html 7 Apr 2003 16:59:26 -0000 1.8.2.4 @@ -1,5 +1,5 @@ -The Request Processor +
The Request Processor By Pete Su
OpenACS docs are written by the named authors, but may be edited @@ -38,7 +38,7 @@ diagram summarizes the stages of the request processor assuming a URL request like http://someserver.com/notes/somepage.adp. -
[D]+
[D]- Stage 1: Search Site Map
The first thing the RP does is to map the given URL to the appropriate Index: openacs-4/packages/acs-core-docs/www/requirements-template.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/requirements-template.html,v diff -u -r1.8.2.3 -r1.8.2.4 --- openacs-4/packages/acs-core-docs/www/requirements-template.html 30 Mar 2003 06:04:04 -0000 1.8.2.3 +++ openacs-4/packages/acs-core-docs/www/requirements-template.html 7 Apr 2003 16:59:26 -0000 1.8.2.4 @@ -1,5 +1,5 @@ -
System/Application Requirements Template By You
+System/Application Requirements Template Index: openacs-4/packages/acs-core-docs/www/rp-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-design.html,v diff -u -r1.6.2.3 -r1.6.2.4 --- openacs-4/packages/acs-core-docs/www/rp-design.html 30 Mar 2003 06:04:04 -0000 1.6.2.3 +++ openacs-4/packages/acs-core-docs/www/rp-design.html 7 Apr 2003 16:59:26 -0000 1.6.2.4 @@ -1,5 +1,5 @@ -
OpenACS 4 Request Processor Design +
OpenACS 4 Request Processor Design by Rafael H. Schloming
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff. Index: openacs-4/packages/acs-core-docs/www/rp-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-requirements.html,v diff -u -r1.6.2.3 -r1.6.2.4 --- openacs-4/packages/acs-core-docs/www/rp-requirements.html 30 Mar 2003 06:04:04 -0000 1.6.2.3 +++ openacs-4/packages/acs-core-docs/www/rp-requirements.html 7 Apr 2003 16:59:26 -0000 1.6.2.4 @@ -1,5 +1,5 @@ -OpenACS 4 Request Processor Requirements +
OpenACS 4 Request Processor Requirements by Rafael H. Schloming
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff. Index: openacs-4/packages/acs-core-docs/www/security-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-design.html,v diff -u -r1.7.2.3 -r1.7.2.4 --- openacs-4/packages/acs-core-docs/www/security-design.html 30 Mar 2003 06:04:04 -0000 1.7.2.3 +++ openacs-4/packages/acs-core-docs/www/security-design.html 7 Apr 2003 16:59:26 -0000 1.7.2.4 @@ -1,5 +1,5 @@ -OpenACS 4 Security Design +
OpenACS 4 Security Design by Richard Li, Archit Shah
OpenACS docs are written by the named authors, but may be edited Index: openacs-4/packages/acs-core-docs/www/security-notes.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-notes.html,v diff -u -r1.8.2.3 -r1.8.2.4 --- openacs-4/packages/acs-core-docs/www/security-notes.html 30 Mar 2003 06:04:04 -0000 1.8.2.3 +++ openacs-4/packages/acs-core-docs/www/security-notes.html 7 Apr 2003 16:59:26 -0000 1.8.2.4 @@ -1,5 +1,5 @@ -OpenACS 4 Security Notes +
OpenACS 4 Security Notes by Richard Li
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff. Index: openacs-4/packages/acs-core-docs/www/security-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-requirements.html,v diff -u -r1.6.2.3 -r1.6.2.4 --- openacs-4/packages/acs-core-docs/www/security-requirements.html 30 Mar 2003 06:04:04 -0000 1.6.2.3 +++ openacs-4/packages/acs-core-docs/www/security-requirements.html 7 Apr 2003 16:59:26 -0000 1.6.2.4 @@ -1,5 +1,5 @@ -OpenACS 4 Security Requirements +
OpenACS 4 Security Requirements by Richard Li
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff. Index: openacs-4/packages/acs-core-docs/www/subsites-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-design.html,v diff -u -r1.6.2.3 -r1.6.2.4 --- openacs-4/packages/acs-core-docs/www/subsites-design.html 30 Mar 2003 06:04:04 -0000 1.6.2.3 +++ openacs-4/packages/acs-core-docs/www/subsites-design.html 7 Apr 2003 16:59:26 -0000 1.6.2.4 @@ -1,5 +1,5 @@ -OpenACS 4 Subsites Design Document +
OpenACS 4 Subsites Design Document by Rafael H. Schloming
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff. Index: openacs-4/packages/acs-core-docs/www/subsites-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-requirements.html,v diff -u -r1.6.2.3 -r1.6.2.4 --- openacs-4/packages/acs-core-docs/www/subsites-requirements.html 30 Mar 2003 06:04:04 -0000 1.6.2.3 +++ openacs-4/packages/acs-core-docs/www/subsites-requirements.html 7 Apr 2003 16:59:26 -0000 1.6.2.4 @@ -1,5 +1,5 @@ -OpenACS 4 Subsites Requirements +
OpenACS 4 Subsites Requirements by Rafael H. Schloming and Dennis Gregorovic
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff. Index: openacs-4/packages/acs-core-docs/www/subsites.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites.html,v diff -u -r1.8.2.3 -r1.8.2.4 --- openacs-4/packages/acs-core-docs/www/subsites.html 30 Mar 2003 06:04:04 -0000 1.8.2.3 +++ openacs-4/packages/acs-core-docs/www/subsites.html 7 Apr 2003 16:59:26 -0000 1.8.2.4 @@ -1,5 +1,5 @@ -Writing OpenACS 4.6.2 Application Pages +
Writing OpenACS 4.6.2 Application Pages By Rafael H. Schloming and Pete Su
Index: openacs-4/packages/acs-core-docs/www/tcl-doc.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tcl-doc.html,v diff -u -r1.8.2.3 -r1.8.2.4 --- openacs-4/packages/acs-core-docs/www/tcl-doc.html 30 Mar 2003 06:04:04 -0000 1.8.2.3 +++ openacs-4/packages/acs-core-docs/www/tcl-doc.html 7 Apr 2003 16:59:26 -0000 1.8.2.4 @@ -1,29 +1,11 @@ -Documenting Tcl Files: Page Contracts and Libraries +
Documenting Tcl Files: Page Contracts and Libraries Tcl procedures: /packages/acs-kernel/tcl-documentation-procs.tcl
In versions of the OpenACS prior to 3.4, the standard -place to document Tcl files (both Tcl pages and Tcl library files) was in -a comment at the top of the file:
-# -# path from server home/filename -# -# Brief description of the file's purpose -# -# author's email address, file creation date -# -# $Id$ -# -
-In addition, the inputs expected by a Tcl page (i.e., form variables) would -be enumerated in a call to ad_page_variables, in effect, -documenting the page's argument list. -
The problem with these practices is that the documentation is only -accessible by reading the source file itself. For this reason, ACS 3.4 -introduces a new API for documenting Tcl files and, on top of that, a -web-based user interface for browsing the documentation:
ad_page_contract: Every Tcl page +
Tcl procedures: /packages/acs-kernel/tcl-documentation-procs.tcl
We use functions to document Tcl files and a web-based user +interface for browsing the documentation:
ad_page_contract: Every Tcl page has a contract that explicitly defines what inputs the page expects (with more precision than ad_page_variables) and incorporates metadata about the page (what used to live in the top-of-page @@ -45,7 +27,7 @@ with the documents API so that each script's contract will document precisely the set of properties available to graphical designers in templates. (Document API integration is subject to change, so we don't -decsribe it here yet; for now, you can just consider +desrribe it here yet; for now, you can just consider ad_page_contract a newer, better, documented ad_page_variables.)
Let's look at an example usage of ad_page_contract:
Index: openacs-4/packages/acs-core-docs/www/templates.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/templates.html,v diff -u -r1.8.2.3 -r1.8.2.4 --- openacs-4/packages/acs-core-docs/www/templates.html 30 Mar 2003 06:04:04 -0000 1.8.2.3 +++ openacs-4/packages/acs-core-docs/www/templates.html 7 Apr 2003 16:59:26 -0000 1.8.2.4 @@ -1,5 +1,5 @@ -
Using Templates in OpenACS 4.6.2 By Pete Su
+Using Templates in OpenACS 4.6.2 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.1.2.1 -r1.1.2.2 --- openacs-4/packages/acs-core-docs/www/tutorial-advanced.html 30 Mar 2003 20:33:12 -0000 1.1.2.1 +++ openacs-4/packages/acs-core-docs/www/tutorial-advanced.html 7 Apr 2003 16:59:26 -0000 1.1.2.2 @@ -3,13 +3,75 @@ by Joel Aufrecht
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff. -This tutorial covers topics which are not essential to creating a minimal working package. Each section can be used independently of all of the others; all sections assume that you've completed the basic tutorial.
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 make your package searchable with OpenFTS/Oracle
How to make your package send email notifications
How to prepare pagelets for inclusion in other pages
How and when to put procedures in a tcl procedure library
How to add general_comments to your pages
More on ad_form - data validation, other stuff. + 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 make your package send email notifications
How to prepare pagelets for inclusion in other pages
How and when to put procedures in a tcl procedure library
How to add general_comments to your pages
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
We need a way to delete records. We'll create a + recursive confirmation page.
Add this column to the table_def in index.tcl
{delete "" {} {<td><a href="note-delete?note_id=$note_id">Delete</a></td>}}Create the delete confirmation/execution page.
[service0@yourserver www]$ emacs note-delete.tcl
ad_page_contract { + A page that gets confirmation and then delete notes. + + @author joel@aufrecht.org + @creation-date 2003-02-12 + @cvs-id $Id$ +} { + note_id:integer + confirm_p:optional +} + +set title "Delete Note" + +if {![exists_and_not_null confirm_p]} { + # first pass, not confirmed. Display a form for confirmation + set note_name [db_string get_name { *SQL }] + set title "Delete $note_name" + template::form::create note-del-confirm + template::element::create note-del-confirm note_id -value $note_id -widget hidden + template::element::create note-del-confirm confirm_p -value 1 -widget hidden + template::element::create note-del-confirm submit \ + -label "Confirm deletion of $note_name" \ + -widget submit +} else { + # second pass, confirmed. Call the database to delete the record + db_1row do_delete { *SQL* } + ad_returnredirect "index" + ad_script_abort +}This page requires a +note_id to determine which record +should be deleted. It also looks for a confirmation variable, which +should initially be absert. If it is absent, we create a form to +allow the user to confirm the deletion. Note that in +entry-edit.tcl we used ad_form to access the Form Template +commands; here, we call them directly because we don't need the extra +features of ad_form. The form calls itself, but +with hidden variables carrying both +note_id and +confirm_p. If confirm_p is present, +we delete the record, set redirection back to the index, and abort +script execution.
The database commands:
[service0@yourserver www]$ emacs note-delete.xql
<?xml version="1.0"?> +<queryset> + <fullquery name="do_delete"> + <querytext> + select samplenote__delete(:note_id) + </querytext> + </fullquery> + <fullquery name="get_name"> + <querytext> + select samplenote__name(:note_id) + </querytext> + </fullquery> +</queryset>
And the adp page:
[service0@yourserver www]$ emacs note-delete.adp
<master> +<property name="title">@title@</property> +<property name="context">{@title@}</property> +<h2>@title@</h2> +<formtemplate id="note-del-confirm"></formtemplate> +</form>The ADP is very simple. The +formtemplate tag outputs the HTML +form generated by the ad_form command with the matching name. Test it by adding the new files in the APM and then deleting a few samplenotes.
You can track comments for any ACS Object. Here we'll track comments for notes. On the notes.tcl/adp pair, which is used to display individual notes, we want to put a link to add comments at the bottom of the screen. If there are any comments, we want to @@ -23,20 +85,20 @@ general_comments package registered, to get its url. You then embed in that url the id of the note and its title, and set the return_url to the current url so that the user can return after - adding a comment.
Now we need to create html that shows any existing comments. + adding a comment.
We need to create html that shows any existing comments. We do this with another general_comments function:
set comments_html [general_comments_get_comments -print_content_p 1 $note_id]First, we pass in an optional parameter that that says to actually show the contents of the comments, instead of just the fact that there are comments. Then you pass the note id, which is also the - acs_object id.
Now we put our two new variables in the notes.adp + acs_object id.
We put our two new variables in the notes.adp page.
<a href="@comment_add_url@">Add a comment</a> -@comments_html@
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-database.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-database.html,v diff -u -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/acs-core-docs/www/tutorial-database.html 30 Mar 2003 20:33:12 -0000 1.1.2.1 +++ openacs-4/packages/acs-core-docs/www/tutorial-database.html 7 Apr 2003 16:59:26 -0000 1.1.2.2 @@ -3,12 +3,12 @@ by Joel Aufrecht
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff. -We create all database objects with scripts in the samplenote/sql/ directory. All database scripts are database-specific and are thus in either the samplenote/sql/oracle or samplenote/sql/postgresql. - Packages can support Oracle, PostgreSQL, or both.
The first file is + Packages can support Oracle, PostgreSQL, or both.
The first file will be samplenote-create.sql. The package manager requires a file with the name packagekey-create.sql, @@ -23,32 +23,65 @@ stored procedures and is fairly complicated even for a simple table. A listing is provided below for you to cut and paste. Comments are located within the source code, with each comment - preceeding the relevant code.
First, create the necessary subdirectories and add them - cvs as you go.
[service0@yourserver samplenote]$ mkdir sql + preceeding the relevant code. (More + info about ACS Objects)
First, create the necessary subdirectories and add them + cvs as you go.
[service0@yourserver samplenote]$ cd /web/service0/packages/samplenote +[service0@yourserver samplenote]$ mkdir sql [service0@yourserver samplenote]$ cvs add sql Directory /cvsroot/service0/packages/samplenote/sql added to the repository [service0@yourserver samplenote]$ cd sql/ [service0@yourserver sql]$ mkdir postgresql [service0@yourserver sql]$ cvs add postgresql Directory /cvsroot/service0/packages/samplenote/sql/postgresql added to the repository -[service0@yourserver sql]$ cd postgresql/ -[service0@yourserver postgresql]$ emacs samplenote-create.sql
Paste this into the file and save and close.
Figure 8.2. Database Creation Script
-- +[service0@yourserver sql]$ cd postgresql/
We break out the sql commands into several files that can + be called independently, and then call all of the create files + from the master create file. The top of each sql file has some + standard comments, including doc tags such as + @author which will be picked up + by the API browser. The string + $Id$ will automatically be + expanded when the file is checked in to cvs.
[service0@yourserver postgresql]$ emacs samplenote-create.sql
Paste this into the file and save and close.
Figure 8.2. Database Creation Script - master create file
-- -- packages/samplenote/sql/postgresql/samplenote-create.sql -- -- @author rhs@mit.edu -- @creation-date 2000-10-22 -- @cvs-id $Id$ -- -- + +\i samplenote-table-create.sql +\i samplenote-functions-create.sql
Create the file to create the database table.
[service0@yourserver postgresql]$ emacs samplenote-table-create.sql
Paste this into the file and save and close.
Figure 8.3. Database Creation Script - table
-- +-- packages/samplenote/sql/postgresql/samplenote-table-create.sql +-- +-- @author rhs@mit.edu +-- @creation-date 2000-10-22 +-- @cvs-id $Id$ +-- -/* We create a temporary function 'inline_0' which we use to -create an ACS Object Type. Each record in our package is a -'samplenote', and each samplenote will be an ACS Object. By making -our records ACS objects, we gain access to the permissions model and -other meta-functions. Each 'samplenote' record will have a matching -record in acs_objects. In general, you should make a table an ACS -Object Type if you expect to apply permissions directly at that level. */ +/* Create the table. Each constraint is named to make it easier to +identify during debugging. The note_id is identical to the object +id. */ +create table samplenote ( + note_id integer constraint samplenote_fk + references acs_objects(object_id) + constraint samplenote_pk + primary key, + title varchar(255) + constraint samplenote_title_nn + not null, + body varchar(1024) +); + + +/* Create a temporary function 'inline_0' which we use to create an +ACS Object Type. Each record in our package is an 'samplenote', and each +samplenote is an ACS Object. That means that each record in the samplenote +table has a corresponding record in acs_objects. By making our +records ACS objects, we gain access to the permissions model and other +meta-functions. In general, you should make a table an ACS Object +Type if you expect to apply permissions directly at that level. */ + create function inline_0 () returns integer as ' begin @@ -57,7 +90,7 @@ ''Sample Note'', -- pretty_name ''Sample Notes'', -- pretty_plural ''acs_object'', -- supertype - ''samplenote'', -- table_name + ''samplenote'', -- table_name ''note_id'', -- id_column null, -- package_name ''f'', -- abstract_p @@ -68,42 +101,44 @@ end;' language 'plpgsql'; select inline_0 (); drop function inline_0 (); +
Create the file to create the functions used to manipulate records.
[service0@yourserver postgresql]$ emacs samplenote-functions-create.sql
Paste this into the file and save and close.
Figure 8.4. Database Creation Script - functions
-- +-- packages/samplenote/sql/postgresql/samplenote-functions-create.sql +-- +-- @author rhs@mit.edu +-- @creation-date 2000-10-22 +-- @cvs-id $Id$ +-- +-- -/* We create the table. Each constraint is named to make it easier to -identify during debugging. The note_id is identical to the object -id.*/ - -create table samplenote ( - note_id integer constraint samplenote_fk - references acs_objects(object_id) - constraint samplenote_pk - primary key, - title varchar(255) - constraint samplenote_title_nn - not null, - body varchar(1024) -); - /* Since each record is also an Object, we make a creation function that will create an object and then use the object id to create a -record in our table. The function also takes several optional input -variables. Creation date will default to now; creation user should be -the user id that will own the object; creation ip is optional; context -id should usually be the package id, which will be explained later.*/ +record in our table. The function also takes several input variables. +Title is required +Body is required +Creation date is optional and defaults to now +Creation user, required, is the user id owns the object +Creation ip is optional +Context id, required, is the id of the package instance. This allows +segregation of records by package, required to make the package +"package-aware." +define_function_args prepares the function to be used by a tcl wrapper function. */ -create function samplenote__new (varchar,varchar,timestamp,integer,varchar,integer) +select define_function_args(samplenote__new,'note_id,title,creation_date,creation_user,creation_ip,context_id'); + +create or replace function samplenote__new (integer,varchar,varchar,timestamptz,integer,varchar,integer) returns integer as ' declare - p_title alias for $1; - p_body alias for $2; - p_creation_date alias for $3; - p_creation_user alias for $4; - p_creation_ip alias for $5; - p_context_id alias for $6; + p_note_id alias for $1; + p_title alias for $2; + p_body alias for $3; + p_creation_date alias for $4; + p_creation_user alias for $5; + p_creation_ip alias for $6; + p_context_id alias for $7; v_samplenote_id int; begin v_samplenote_id := acs_object__new ( - null, + p_note_id, ''samplenote'', p_creation_date, p_creation_user, @@ -116,15 +151,17 @@ (v_samplenote_id, p_title, p_body); PERFORM acs_permission__grant_permission( v_samplenote_id, - p_owner_id, + p_creation_user, ''admin'' ); return v_samplenote_id; end;' language 'plpgsql'; /* The __delete function deletes a record and all related overhead. */ -create function samplenote__delete (integer) + +select define_function_args('samplenote___delete','note_id'); +create or replace function samplenote__delete (integer) returns integer as ' declare p_samplenote_id alias for $1; @@ -144,31 +181,36 @@ can be identified. Now we have to build that function. In this case, we'll return a field called title as the name. */ -create function samplenote__name (integer) +select define_function_args('samplenote___name','note_id'); + +create or replace function samplenote__name (integer) returns varchar as ' declare p_samplenote_id alias for $1; v_samplenote_name samplenote.title%TYPE; begin select title into v_samplenote_name from samplenote - where samplenote_id = p_samplenote_id; + where note_id = p_samplenote_id; return v_samplenote_name; end; ' language 'plpgsql';
Create a database file to drop everything if the package - is uninstalled.
[service0@yourserver postgresql]$ emacs samplenote-drop.sql
Figure 8.3. Database deletion script
-- packages/samplenote/sql/samplenote-drop.sql + is uninstalled.
[service0@yourserver postgresql]$ emacs samplenote-drop.sql
Figure 8.5. Database deletion script
-- packages/samplenote/sql/samplenote-drop.sql -- drop script -- +-- @author rhs@mit.edu +-- @creation-date 2000-10-22 +-- @cvs-id $Id$ +-- /* This script removes from the database everything associated with our table. */ ---drop functions -drop function samplenote__new (varchar,varchar,timestamp,integer,varchar,integer); -drop function samplenote__delete (integer); -drop function samplenote__name (integer); +--drop package, which drops all functions created with define_function_args +select drop_package('samplenote'); + --drop permissions delete from acs_permissions where object_id in (select note_id from samplenote); @@ -210,25 +252,48 @@ done (many lines omitted) done -[service0@yourserver samplenote]$
Now run the create script manually to add your tables and functions.
[service0@yourserver samplenote]$ cd sql/postgresql/ +[service0@yourserver samplenote]$
Run the create script manually to add your tables and functions.
[service0@yourserver samplenote]$ cd sql/postgresql/ [service0@yourserver postgresql]$ psql -f samplenote-create.sql +psql:samplenote-table-create.sql:22: NOTICE: CREATE TABLE / PRIMARY KEY will create implicit index 'samplenote_pk' for table 'samplenote' +psql:samplenote-table-create.sql:22: NOTICE: CREATE TABLE will create implicit +trigger(s) for FOREIGN KEY check(s) CREATE +CREATE inline_0 ---------- 0 (1 row) DROP -psql:samplenote-create.sql:51: NOTICE: CREATE TABLE / PRIMARY KEY will create implicit index 'samplenote_pk' for table 'samplenote' -psql:samplenote-create.sql:51: NOTICE: CREATE TABLE will create implicit trigger(s) for FOREIGN KEY check(s) + define_function_args +---------------------- + 1 +(1 row) + CREATE + define_function_args +---------------------- + 1 +(1 row) + CREATE + define_function_args +---------------------- + 1 +(1 row) + CREATE -CREATE -[service0@yourserver postgresql]$If there are errors, use them to debug the sql file and try again. Once you get the same output as shown above, test the drop script:
[service0@yourserver postgresql]$ psql -f samplenote-drop.sql -DROP -DROP -DROP +[service0@yourserver postgresql]$
If there are errors, use them to debug the sql file and try again. If there are errors in the database table creation, you may need to run the drop script to drop the table so that you can recreate it. The drop script will probably have errors since some of the things it's trying to drop may be missing. They can be ignored.
If there are errors creating the functions, you can re-run the function creation file directly after fixing it, because all of the functions are created with create or replace commands. This will also make it easier to fix mistakes within the functions that aren't apparent until the functions are used. And it will make upgrades easier.
Once you get the same output as shown above, test the drop script:
[service0@yourserver postgresql]$ psql -f samplenote-drop.sql +psql:samplenote-drop.sql:13: NOTICE: DROP PACKAGE: samplenote +psql:samplenote-drop.sql:13: NOTICE: DROPPING FUNCTION: samplenote__delete +psql:samplenote-drop.sql:13: NOTICE: DROPPING FUNCTION: samplenote__name +psql:samplenote-drop.sql:13: NOTICE: DROPPING FUNCTION: samplenote__new +psql:samplenote-drop.sql:13: NOTICE: PACKAGE: samplenote: DROPPED + drop_package +-------------- + +(1 row) + DELETE 0 CREATE inline_0 @@ -237,8 +302,8 @@ (1 row) DROP -psql:samplenote-drop.sql:33: NOTICE: DROP TABLE implicitly drops referential integrity trigger from table "acs_objects" -psql:samplenote-drop.sql:33: NOTICE: DROP TABLE implicitly drops referential integrity trigger from table "acs_objects" +psql:samplenote-drop.sql:35: NOTICE: DROP TABLE implicitly drops referential integrity trigger from table "acs_objects" +psql:samplenote-drop.sql:35: NOTICE: DROP TABLE implicitly drops referential integrity trigger from table "acs_objects" DROP acs_object_type__drop_type ---------------------------- Index: openacs-4/packages/acs-core-docs/www/tutorial-debug.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-debug.html,v diff -u -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/acs-core-docs/www/tutorial-debug.html 30 Mar 2003 20:33:12 -0000 1.1.2.1 +++ openacs-4/packages/acs-core-docs/www/tutorial-debug.html 7 Apr 2003 16:59:26 -0000 1.1.2.2 @@ -3,24 +3,26 @@ by Joel Aufrecht
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff. -PostgreSQL.�You can work directly with the database to do debugging steps like looking directly at tables and testing stored procedures. Start emacs. Type M-x sql-postgres. Press enter for server name and use openacs-dev for database name. You can use C-(up arrow) and C-(down arrow) - for command history.
Watching the server log.�NOTE: explain how to add tcl to directly write your own log outputTo set up real-time monitoring of the Aolserver error + for command history.
Hint: "Parse error near *" usually means that an xql file + wasn't recognized, because the tcl file is choking on the *SQL* + placeholder that it falls back on.
Watching the server log.�NOTE: explain how to add tcl to directly write your own log outputTo set up real-time monitoring of the Aolserver error log, type
less /usr/local/aolserver/log/openacs-dev-error.log
-F�to�show�new�log�entries�in�real�time�(like�tail�-f)
C-c�to�stop�and�F�to�start�it�up�again.�
G�goes�to�the�end.
?�searches�backward�
/�searches�forward.�
����������Make a list of basic tests to make sure it works
Test Num Action Expected Result 001 Browse to the index page while not logged in and + Make a list of basic tests to make sure it works
Test Num Action Expected Result 001 Browse to the index page while not logged in and while one or more notes exist. No edit or delete or add links should appear. 002 Browse to the index page while logged in. An Edit link should appear. Click on it. Fill out the form and click Submit. The text added in the form should be visible on the index page. Other things to test: try to delete someone else's note. Try to delete your own note. Edit your own note. - Search for a note.
View comments on this page at openacs.org + Search for a note.View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html,v diff -u -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html 30 Mar 2003 20:33:12 -0000 1.1.2.1 +++ openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html 7 Apr 2003 16:59:26 -0000 1.1.2.2 @@ -3,74 +3,91 @@ by Joel Aufrecht
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff. -To start developing new code in OpenACS, we build a new package. A package is a a discrete collection of web pages, tcl code, and database tables and procedures. A package can be installed, upgraded, and removed. It communicates with other packages through an API. This chapter walks you through the - minimum steps to create a useful package, including:
How to use the APM to start a new package
How to write documentation, including self-documenting code
How to set up the database tables and procedures.
How to write web pages.
How to add automated regression testing to your packages
How to debug your package
You will need:
A computer with a working installation of OpenACS + minimum steps to create a useful package, including writing + documentation, setting up database tables and procedures, + writing web pages, debugging, and automatic regression testing. +
You will need:
A computer with a working installation of OpenACS 4.6. If you don't have this, see Installation Overview.
Example files, which are included in the standard OpenACS 4.6.2 distribution. -
Figure 8.1. Assumptions in this section
Fully qualified domain name of your server yourserver.test URL of your server http://yourserver.test:8000 Name of development account service0 New Package key samplenote Tee ACS Package Manager initializes new packages. This sets - up the initial directories, meta-information files, and - database entries for a new package. +
Figure 8.1. Assumptions in this section
Fully qualified domain name of your server yourserver.test URL of your server http://yourserver.test:8000 Name of development account service0 New Package key samplenote We use the ACS Package Manager (APM) to add, remove, and + upgrade packages. It handles package meta-data, such as lists of + files that belong in the package. Each package is uniquely + identified by a package key. To start developing a new + package, use the APM to create an empty package with our new + package key, samplenote. This will create + the initial directories, meta-information files, and database + entries for a new package. (More info on APM)
Browse to http://yourserver:8000/acs-admin/apm.
Click Create a New Package.
Fill in the fields listed below. Tab through the rest. (Some will change automatically. Don't mess with those.)
Package Key: samplenote
Package Name: - Notes (Sample Application) + Notes
Package Plural: - Notes (Sample Applications)
+ Notes
Initial Version: 0.1d
Summary: This is my first package. -
At the bottom, click - . -
At the bottom, click + . +
This creates a package rooted at + /web/service0/packages/samplenote. + This is the "home directory" of our new package, and all + files in the package will be within this directory.
In order to see your work in progress, you must create a map between the URL space of incoming requests and the package. - You do this by mounting the package in the Site Map.
Browse to -http://yourserver:8000/admin/site-map/.
Click the new sub - folder link on the Main Site - line.
Type samplenote -and click .
Click the new -application link on the samplenote line.
Type Sample Note -where it says + You do this by mounting the package in the Site Map. This + creates a link between the incoming URL and an + instance of the package. (More on Site Maps and nodes)
You can have + multiple instances of a package on one site, each with a + different URL and different permissions, all sharing the same + code and tables. This requires that a package be developed + package-aware. You'll see how to do that + in this tutorial.
Browse to +http://yourserver.test:8000/admin/site-map/.
Click the new sub + folder link on the top row in the + Site Map table.
Type note +and click .
This creates a new row called +note. In the new row, click the new +application link
Type Sample Note where +it says untitled, choose -Notes (Sample Application) from the -drop-down list, and click -. +Notes from the drop-down list, and +click .
By mounting the package, we've caused all requests to - http://yourserver.test/samplenote - to be satisfied from the files at /web/service0/packages/samplenote/www.
It's time to document. For a new package you should - start by copying the documentation template from + http://yourserver.test:8000/note + to be satisfied from the files at /web/service0/packages/samplenote/www.
It's time to document. For the tutorial we'll use + pre-written documentation. When creating a package + from scratch, start by copying the documentation template from /web/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-documentation-template.xml to - yourpackage/www/docs/xml/package-documentation.xml.
You then open that file with emacs, write the - requirements and design section, generate html, and start - coding. For this tutorial, you should instead install the - pre-written documentation files for the tutorial app, examine - them, generate html, read it, and then proceed to build the - package. Store any diagrams in native format in the - www/doc/xml directory, and - store png or jpg versions of the diagrams in the - www/doc direcory.
Pre-written documentation is available for this - tutorial, so we'll copy that documentation and edit it. Log in + yourpackage/www/docs/xml/index.xml.
You then edit that file with emacs to write the + requirements and design sections, generate the html, and start + coding. Store any supporting files, like page maps or schema + diagrams, in the www/doc/xml + directory, and store png or jpg versions of supporting files in the + www/doc directory.
For this tutorial, you should instead install the + pre-written documentation files for the tutorial app. Log in as service0, create the standard directories, and copy the prepared documentation:
[service0@anthrax service0]$ cd /web/service0/packages/samplenote/ [service0@anthrax samplenote]$ mkdir -p www/doc/xml -[service0@anthrax samplenote]$ cp /web/service0/packages/acs-core-docs/www/files/samplenote/* www/doc/xml/ -[service0@anthrax samplenote]$ mv www/doc/xml/*.dia www/doc/ -[service0@anthrax samplenote]$ mv www/doc/xml/*.png www/doc/ -[service0@anthrax samplenote]$
OpenACS uses DocBook for documentation. DocBook is +[service0@anthrax samplenote]$ cd www/doc/xml +[service0@anthrax xml]$ cp /web/service0/packages/acs-core-docs/www/files/samplenote/* . +[service0@anthrax xml]$
OpenACS uses DocBook for documentation. DocBook is an XML standard for semantic markup of documentation. That means that the tags you use indicate meaning, not intended - appearance. The style sheet will determine appearance.
Open the file index.xml + appearance. The style sheet will determine appearance. You + will edit the text in an xml file, and then process the file + into html for reading.
Open the file index.xml in emacs. Examine the file. Find the version history (look for the tag <revhistory>). Add a new record to the document version history. Look for the @@ -81,14 +98,12 @@ is stored in the www/docs/ directory. A Makefile is provided to generate html from the xml, and copy all of the supporting files. If Docbook is set up correctly, all you need - to do is:
[service0@anthrax samplenote]$ cd www/doc/xml -[service0@anthrax xml]$ make + to do is:
[service0@anthrax xml]$ make cd .. ; /usr/bin/xsltproc ../../../acs-core-docs/www/xml/openacs.xsl xml/index.xml Writing requirements-introduction.html for sect1(requirements-introduction) Writing requirements-overview.html for sect1(requirements-overview) Writing requirements-cases.html for sect1(requirements-cases) Writing sample-data.html for sect1(sample-data) -Writing sample-data.html for sect1(sample-data) Writing requirements.html for chapter(requirements) Writing design-data-model.html for sect1(design-data-model) Writing design-ui.html for sect1(design-ui) @@ -100,10 +115,11 @@ Writing bi01.html for bibliography Writing index.html for book [service0@yourserver xml]$
Verify that the documentation was generated and reflects - your changes in the xml by browsing to http://yoursite:8000/samplenote/doc
Before you do any more work, make sure that your work is + your changes by browsing to http://yoursite:8000/samplenote/doc
Before you do any more work, make sure that your work is protected by putting it all into cvs. The cvs add command is not recursive, so you'll have to - traverse the directory tree manually and add as you go.
[service0@yourserver xml]$ cd .. + traverse the directory tree manually and add as you go. (More on + CVS)
[service0@yourserver xml]$ cd .. [service0@yourserver doc]$ cd .. [service0@yourserver www]$ cd .. [service0@yourserver samplenote]$ cd .. Index: openacs-4/packages/acs-core-docs/www/tutorial-pages.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-pages.html,v diff -u -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/acs-core-docs/www/tutorial-pages.html 30 Mar 2003 20:33:12 -0000 1.1.2.1 +++ openacs-4/packages/acs-core-docs/www/tutorial-pages.html 7 Apr 2003 16:59:26 -0000 1.1.2.2 @@ -3,7 +3,7 @@ by Joel Aufrecht
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff. -Each user-visible page in your package has, typically, three parts. The xql file contains any database queries, the tcl file holds the procedural logic for the page and does things like check permissions, invoke the database queries, and modify @@ -12,15 +12,8 @@ index, so we'll build that first, starting with the tcl file:
[service0@yourserver samplenote]$ cd /web/service0/packages/samplenote/www -[service0@yourserver www]$ emacs index.tcl
Paste this into the file. There are several things to -note about the file:
The page begins with an - ad_page_contract function. - This is where we declare the input and output variables and - their types and restrictions. It's also where we document the - page, including descriptions of the parameters and return.
We have one input variable, - orderby, which is optional - and defaults to title.
We have one output variable, table_html
We populate the table_html variable with a function call, ad_table, which does most of the work of generating an html table from a database recordset. We pass it several parameters:
- -Torderby $orderby
If the user has selected a column for sorting, this passes that information to the function.
- notes_query
This is the name of the SQL query that we'll put in the xql file.
- { *SQL* }
This is a dummy placeholder. It's possible to put sql directly in the tcl file, but this is deprecated because it's harder to make portable.
- $table_def
Here we pass in the variable we just constructed; it contains a list of column names and display titles.
ad_page_contract { - This is the main page for the package. It displays all of the Sample Notes\ and provides links to edit them and to create new Notes. +[service0@yourserver www]$ emacs index.tclPaste this into the file.
ad_page_contract { + This is the main page for the package. It displays all of the Notes and provides links to edit them and to create new Notes. @author rhs@mit.edu @creation-date 2000-10-23 @@ -38,11 +31,19 @@ {title "Note"} {body "Contents"} {edit "" {} {<td><a href="note-edit?note_id=$note_id">Edit</a></td>}} - {delete "" {} {<td><a href="note-delete?note_id=$note_id">Delete</a></td>}} } # construct an html table from the samplenotes database table -set table_html [ad_table -Torderby $orderby notes_query { *SQL* } $table_def]Now put the database query into a separate file. If the +set table_html [ad_table -Torderby $orderby notes_query { *SQL* } $table_def]
There are several things to +note about the file:
The page begins with an + ad_page_contract function. + This is where we declare the input and output variables and + their types and restrictions. It's also where we document the + page, including descriptions of the parameters and return. + (More information about TCL + pages and page contracts)
We have one input variable, + orderby, which is optional + and defaults to title.
We have one output variable, table_html
We populate the table_html variable with a function call, ad_table, which does most of the work of generating an html table from a database recordset. We pass it several parameters:
- -Torderby $orderby
If the user has selected a column for sorting, this passes that information to the function.
- notes_query
This is the name of the SQL query that we'll put in the xql file.
- { *SQL* }
This is a dummy placeholder. It's possible to put sql directly in the tcl file, but this is deprecated because it's harder to make portable.
- $table_def
Here we pass in the variable we just constructed; it contains a list of column names and display titles.
Put the database query into a separate file. If the database query is exactly the same for Oracle and PostgreSQL, it can go into a file with the same name as the tcl file but an xql extension, e.g., index.xql. If @@ -65,23 +66,46 @@ [ad_order_by_from_sort_spec $orderby $table_def] </querytext> </fullquery> -</queryset>
Now we create the user-visible page.
[service0@yourserver www]$ emacs index.adp
The first line indicates that this page should be rendered within the the master template, which defaults to /web/service0/www/default-master. The second line passes a title variable to the master template. The third line inserts the contents of the variable table_html. The last line is a link to a page we haven't created yet.
<master> +</queryset>
Create the user-visible page.
[service0@yourserver www]$ emacs index.adp
The first line indicates that this page should be rendered within the the master template, which defaults to /web/service0/www/default-master. The second line passes a title variable to the master template. The third line inserts the contents of the variable table_html. The last line is a link to a page we haven't created yet.
<master> <property name="title">Sample Notes</property> @table_html@ -<p><a href="note-edit">Add a note</a></p>
Before we can test these files, we have to notify the package manager that they exist. (To be precise, the tcl and adp will work fine as-is, but the xql file will not be recognized until we tell the APM about it.).
Go to http://yourserver.test:8000/acs-admin/apm
Click on the samplenote link
Click Manage file information
Click Scan the packages/samplenote directory for additional files in thispackage
Click add checked files
Now that the pages are in the APM, check to make sure that the self-documenting code is working.
Browse to http://yourserver:8000/api-doc/
Click # Notes (Sample Application) 0.1d
Click Content Pages
Click index.tcl and examine the results.
Go to http://192.168.0.2:8000/samplenote/. You should see something like this:
+<p><a href="note-edit">Add a note</a></p>
Before we can test these files, we have to notify the + package manager that they exist. (More precisely, the tcl and + adp will work fine as-is, but the xql file will not be + recognized until we tell the APM about it.).
Go to http://yourserver.test:8000/acs-admin/apm
Click on the samplenote link
Click Manage file information
Click Scan the packages/samplenote directory for additional files in thispackage
Click add checked files
On the list of files, on the + index.xql line, click + watch. Unlike adp and tcl + pages, xql pages get cached. (And new xql files don't get + loaded when they're added.) Watching an xql file causes the APM + to load the contents of the XQL into memory so that it can be + used, and to reload it whenever the file is changed. The + watch will last until the server is restarted.
Now that the pages are in the APM, check to make sure that the self-documenting code is working.
Browse to http://yourserver.test:8000/api-doc/
Click Notes 0.1d
Click Content Pages
Click index.tcl and examine the results.
Go to http://yourserver.test:8000/note/. You should see this:
Sample Notes Your Workspace : Main Site : Sample Note No data found. +Add a note. + foo@yourserver.test -
Since our table is empty, it's a pretty boring page. So next we'll make it possible to add records.
If you get any other output, such as an error message, skip to the section called “Debugging and Automated Testing”. Note also that, while tcl and adp pages update automatically, xql pages get cached. So if you change an xql page, the change won't take effect unless you restart the server, reload the package via the APM, or put a watch on the file in the APM file list. With a watch, which lasts until the next service restart, the file will be updated each time it is changed on disk.
We'll create a single page to handle both adding and editing records. First, create the tcl:
[service0@yourserver www]$ emacs note-edit.tcl
The page takes a single, optional input parameter, note_id. If it's present, logic within ad_form will assume that we're editing an existing record. We check user_id with ad_maybe_redirect_for_registration, which will redirect to the login page (with an automatic return path to bring them back after login or registration) if the visitor isn't logged in. Then we call ad_form, specifying the primary key of the table, the fields we want to edit, and functions for insert and update.
ad_page_contract { +Since our table is empty, it's a pretty boring page. So next we'll make it possible to add records.
If you get any other output, such as an error message, skip to the section called “Debugging and Automated Testing”.
We'll create a single page to handle both adding and + editing records. In this recursive approach, the same tcl + function can present a blank HTML form, present the same form + pre-loaded with an existing record, and handle the resulting + submission of either updated or new records. This recursive + approach reduces the total amount of code and files. First, + create the tcl:
[service0@yourserver www]$ emacs note-edit.tcl
Paste and save and edit:
ad_page_contract { Simple add/edit form for samplenote. } { - note_id:optional + note_id:integer,optional } set user_id [ad_maybe_redirect_for_registration] +set title "Add a note" +if {[exists_and_not_null note_id]} { + set title "Edit a note" +} + ad_form -name note -form { note_id:key {title:text @@ -91,17 +115,30 @@ {label "Body"} } } -select_query_name note_query -new_data { -db_1row do_insert { *SQL* } +samplenote::new db_1row do_insert { *SQL* } } -edit_data { db_dml do_update { *SQL* } } -after_submit { ad_returnredirect "index" -ad_script_abort -}Next, we create the database functions.
[service0@yourserver www]$ emacs note-edit.xql
<?xml version="1.0"?> +}
We use ad_form + to automate most of the work here. Ad_form is a wrapper for the + template + functions for creating HTML forms. These functions should + always be used for HTML forms; this promotes consistency and, + since all template functions use the same stylesheet system, makes it easy to change + the appearance of forms.
The page takes a single, optional input parameter, + note_id. If it's present, ad_form will assume that we're editing + an existing record, look up that record, and pre-populate the + form. We'll also check and change the page title if necessary. We check user_id with ad_maybe_redirect_for_registration, + which will redirect to the login page (with an automatic return + path to bring them back after login or registration) if the + visitor isn't logged in. Then we call ad_form, specifying the + primary key of the table, the fields we want to edit, and + functions for insert and update.
Next, we create the database functions.
[service0@yourserver www]$ emacs note-edit.xql
<?xml version="1.0"?> <queryset> <fullquery name="do_insert"> <querytext> - select samplenote__new(:title, :body,null,:user_id,null,null) + select samplenote__new(null,:title, :body,null,:user_id,null,null) </querytext> </fullquery> <fullquery name="do_update"> @@ -120,57 +157,22 @@ where note_id = :note_id </querytext> </fullquery> -</queryset>And now the user-visible page:
[service0@yourserver www]$ emacs note-edit.adp
<master> -<formtemplate id="note"></formtemplate> -
Go to the APM as before and scan for new files and add your new work. Then test all this by going to the package home page and adding and editing a few records.
Now we need a way to delete records. We'll create a recursive confirmation page.
[service0@yourserver www]$ emacs note-delete.tcl
This page requires a note_id to determine which record should be deleted. It also looks for a confirmation variable, which should initially be absert. If it is absent, we create a form to allow the user to confirm the deletion. The form calls the same page, but with hidden variables carrying both note_id and confirm_p.
ad_page_contract { - A page that gets confirmation and then delete notes. - - @author joel@aufrecht.org - @creation-date 2003-02-12 - @cvs-id $Id$ -} { - note_id:integer - confirm_p:optional -} - -set title "Delete Note" - -if {[exists_and_not_null confirm]} { - # if confirmed, call the database to delete the record - db_1row do_delete { *SQL* } - ad_returnredirect "index" -} else { - # if not confirmed, display a form for confirmation - set note_name [db_string get_name { *SQL }] - set title "Delete $note_name" - template::form::create note-del-confirm - template::element::create note-del-confirm note_id -value $note_id -widget \hidden - template::element::create note-del-confirm confirm_p -value 1 -widget hidden -}Now the database calls:
[service0@yourserver www]$ emacs note-delete.xql
<?xml version="1.0"?> -<queryset> - <fullquery name="do_delete"> - <querytext> - select samplenote__delete(:note_id) - </querytext> - </fullquery> - <fullquery name="get_name"> - <querytext> - select samplenote__name(:note_id) - </querytext> - </fullquery> -</queryset>
And the adp page:
[service0@yourserver www]$ emacs note-delete.adp
<master> +</queryset>
Create the user-visible page:
[service0@yourserver www]$ emacs note-edit.adp
<master> <property name="title">@title@</property> -<h2>@title@</h2> -<formtemplate id="note-del-confirm"></formtemplate> -</form>
Now test it by adding the new files in the APM and then deleting a few samplenotes.
Put your new work into source control.
[service0@yourserver www]$ cvs add *.adp *.tcl *.xql +<property name="context">{@title@}</property> +<formtemplate id="note"></formtemplate> +The property tags are passed to the master template, which + uses their values to set the page title and context bar + (breadcrumb trail). We use the same variable, + title, for both variables but + wrap it in curly brackets for context so that the spaces aren't + interpreted separators. The formtemplate tag outputs the form + html with the matching name.
Go to the APM as before and scan for new files and add your new work. Then test all this by going to the package home page and adding and editing a few records.
Put your new work into source control.
[service0@yourserver www]$ cvs add *.adp *.tcl *.xql cvs add: cannot add special file `CVS'; skipping cvs add: doc/CVS already exists cvs add: scheduling file `index.adp' for addition cvs add: scheduling file `index.tcl' for addition cvs add: scheduling file `index.xql' for addition -cvs add: scheduling file `note-delete.adp' for addition -cvs add: scheduling file `note-delete.tcl' for addition -cvs add: scheduling file `note-delete.xql' for addition cvs add: scheduling file `note-edit.adp' for addition cvs add: scheduling file `note-edit.tcl' for addition cvs add: scheduling file `note-edit.xql' for addition Index: openacs-4/packages/acs-core-docs/www/files/config.tcl.txt =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/files/config.tcl.txt,v diff -u -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/acs-core-docs/www/files/config.tcl.txt 2 Apr 2003 17:57:48 -0000 1.1.2.1 +++ openacs-4/packages/acs-core-docs/www/files/config.tcl.txt 7 Apr 2003 16:59:54 -0000 1.1.2.2 @@ -44,7 +44,7 @@ # ns_section ns/parameters -ns_param serverlog ${serverroot}/log/${server}-error.log +ns_param serverlog ${serverroot}/log/error.log ns_param home $homedir ns_param maxkeepalive 0 ns_param logroll on @@ -202,7 +202,7 @@ if { $database == "oracle" } { ns_param ora8 ${bindir}/ora8.so } else { - ns_param postgres ${bindir}/postgres.so ;# Load PostgreSQL driver + ns_param postgres ${bindir}/nspostgres.so ;# Load PostgreSQL driver } # Index: openacs-4/packages/acs-core-docs/www/files/samplenote/data-model.dia =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/files/samplenote/Attic/data-model.dia,v diff -u -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/acs-core-docs/www/files/samplenote/data-model.dia 2 Apr 2003 17:58:03 -0000 1.1.2.1 +++ openacs-4/packages/acs-core-docs/www/files/samplenote/data-model.dia 7 Apr 2003 17:00:22 -0000 1.1.2.2 @@ -1,7 +1,5 @@ - � �Is�0��� ���I�$-M:� �� �=����ʒ�䦹�ۑ�&��@g����>=�mru{������.��1�5�s1�,���>^.���٭�э��p�i�T�-�����i�v;����� �"�J��Wg��\��$ -ǒQ$%�v A�ȃ�n#�~�Y@]=�J� F� Y���襛�3��n ���j=� �D��ω�� �?�I��������������B����<�"�B̌�l6{Z��{x ��G`a��K���cl� �$�=G8�(�9eʴ��5��U����c@<|�������= �)�-;�ʭ�8�r���i���f���M������ `D�N�eJ4m1���\] �L���'�� ˓��q��V��?���y߿|�.� � K�*��]�_'��Z�4�̓[ � 6qf̯.�ƫ�����,�vV?W�GtC��og��|��X��h@�� �i���gR��7o�!p��BY�����r��h9�Ls�j-d�z,�e -��& !� ���j��V FNnaN�F�|���� -18���I�����uM��MFPM�ڃC�'��s�b����Վs<.Ts�dž�Q�T�I�5�9���,�X�N�Sr��&�g��q�z�ZE��$v��{F���v�4�Z��'m+Zj�j`�}lW%g��> -�+�v�1��A8��V �OTQ �%�� wى=]Js��@jу$���B`�� 4�W�;a -�����ț-���i�+- YourApplication +Tutorial Application 1 -26 Dec 2002 +27 Dec 2002 Joel Aufrecht -Consolidated and shortened existing OpenACS - documentation; added some ideas from Construx +First Draft - -0.3 -5 Sep 2000 -Kai Wu -Edited further, incorporated feedback from Michael Yoon -- -0.2 -22 Aug 2000 -Kai Wu -Edited -- 0.1 -21 Aug 2000 -Josh Finkler, Audrey McLoghlin -Created -($Id$) - Your -Name +Joel +Aufrecht - youremail +joel@aufrecht.org Introduction - This package does .... Summarize the rest of this - document in one paragraph. + This package lets users post blocks of text to the web, which + others can then read. It integrates with full text search. + It is intended to show new developers how to accomplish basic + tasks with OpenACS. Overview - The components of this package are ... List the - major components and their functions. + This package has a simple data component: text notes, stored + in a table in the database. The other component is the user + interface. It also needs support Full Text Search. There is + no administrative interface. - This package depends on ... List other packages, - other software, and any external processes that the package - needs. + This package depends on the core OpenACS functionality and on + OpenFTS. It is PostGreSQL-only - it has not been ported to + Oracle. - Define any abbreviations or other special terms. + OpenFTS is the third-party PostGreSQL full text search engine. Use-cases and User-scenarios -List some people who would use this package. - Describe how they would use it, how it would be better than what - they are doing now, and how it compares to alternatives. - Include specific, real sample data if possible. - User 1 -This user will accomplish X with the package. - Currently, the user does X with product Y, which takes - several hours and costs too much. +Author +Authors write notes, which comprise titles and + bodies, both of plain text. Currently authors do this by + ftping files to a web server, which generates many support + calls. - User 1 adds and edits stuff ... +An Author creates a new note, such as the following: ++ + ++ + ++ +Hello World +This is my first OpenACS package. +- +User1 Views stuff ... +An Author changes a note previously written. + Authors can't change other authors' notes. + An Author deletes a note that is no longer + needed. Unless explicitly deleted, notes should never disappear. ++ + +Reader +Readers can see all of the existing notes. + Currently readers browse to a web page and read the + notes. They use the browser search function to find notes + of interest. ++ ++ +An Reader browses the notes. ++ +An Reader searches for notes. +- - -Sample Data -An example of data stored in the package is ... -Prioritized Requirements -A list of requirements, split up into functional - areas. In the ideal requirements document, all requirements are - sufficiently specific, detailed, precise, and comprehensive that - the package can be designed and built without any other - directions, and two different packages built to meet the same - requirements will be similar internally and have identical - APIs. Requirements are prioritized relative to a release - cycle. All priority A requirements must be satisfied before the - package can be released. Priority B requirements are - desired but should be cut as soon as possible if the schedule is - threatened. Priority X requirements should not be implemented - in this cycle; at the beginning of the next cycle, they should - be promoted to A or B or removed. - +System Interfaces -Describe all of the interfaces between the - package and other OpenACS packages, the OpenACS API, the host - computer, and network clients. Include sample conversations - for any external APIs. Describe any API the package will - provide. - Interface1 -General description. +Full Text Search +All text entered into the package should be searchable + via OpenFTS. The OpenFTS interface is specified at ???. + Number Priority Description -100 A A critical requirement. 110 B An optional requirement. 120 X A requirement deferred for - this cycle. 100 A The Title and + Body fields are indexed by Full Text Search. User Interfaces User 1 Interface -Use storyboards and drawings to describe - what a typical user will see and how User 1 will use the product. - This includes web interfaces, email. ++ ++ ++ + +A picture of the user interface. +An Author browses to the home page of the package and + sees a list of existing notes. ++ + 200 A An Author can + see all existing notes. 210 A An Author can + add a new note. 220 A If an author + wrote a note, the author can edit that note. 225 A If an author + wrote a note, the author can delete that note. 230 A Authors must + be OpenACS site members. 235 A Authors + authenticate themselves via the OpenACS login + system. - -Administrator Interface +Reader Interface +An Reader can see all existing notes. ++ + 300 A A Reader can + see all existing notes. - - -Instance Customization -- -Customization -What will have to change in a typical - installation? What are reasonable defaults? -Internationalization ++ + 400 B Postings can + be in any language. Security -How sensitive is the data stored? Can users - see or edit each other's data? What cryptography is required? - What logs should be kept, who should monitor them, and how? - +The only security need is that authors not be able to + change or delete other authors' notes. This can be enforced + with built-in OpenACS security. ++ + 500 A There is no logging. - -Data Storage -Data Model ++ -+ ++ + +A picture of the data model +- -The data model discussion should address the intended usage - of each entity (table, trigger, view, procedure, etc.) when this - information is not obvious from an inspection of the data model - itself. If a core service or other subsystem is being used (e.g., the - new parties and groups, permissions, etc.) this should also be - mentioned. Any default permissions should be identified herein. Discuss any data model extensions which tie into other - packages. - -- -Transactions -Discuss modifications which the database may undergo from - your package. Consider grouping legal transactions according to - the invoking user class, i.e. transactions by an OpenACS-admin, by - subsite-admin, by a user, by a developer, etc. -- Table1 -Description of table. -- + Tutorialnote +This table holds the notes. Each note is one + record. ++ - +Field Description Relationships Type Sample Value - +fieldname -Indicates ... -Primary Key... References ... -int +tutorialnote_id + Primary Key. References acs_objects(object_id). + +owner_id +Indicates the owner of + the note. +References users(user_id). ++ +title +Plain text title of the note ++ varchar(255) +Hello, world ++ body +Body text of the note ++ varchar(2024) +This is my first package +Each note is an acs object. +This means that + each record in the note table has a corresponding set of + entries in the core acs tables, where security and other + things are handled. This integrates our package with OpenACS + to use the existing security stuff. It complicates our + database scripts, because there are extra steps to create and + delete records. It also greatly complicates dropping the + package because we have to carefully clean out any matching + records - in the correct order to avoid breaking dependent + relationships - before dropping our new table. Use the standard stored procedures for add, delete, and + name. +Use ??? for full text search integration. User Interface -- In this section, discuss user interface issues and pages to be built; - you can organize by the expected classes of users. These may include: - -- - -Developers OpenACS administrators (previously known as site-wide administrators) Subsite administrators End users - You may want to include page mockups, site-maps, or other visual aids. - Ideally this section is informed by some prototyping you've done, to - establish the package's usability with the client and other interested - parties. - - -- Note: In order that developer documentation be uniform across - different system documents, these users should herein be designated as - "the developer," "the OpenACS-admin," "the sub-admin," and "the user," - respectively. - ++ -+ ++ + +A picture of the page map. +- Finally, note that as our templating system becomes more entrenched - within the OpenACS, this section's details are likely to shift from UI - specifics to template interface specifics. - -+ -index +Fetch all existing notes and display them. For each + note, if the viewer has write permission on the note, show an + edit link. At the bottom of the page, if the viewer has + permission to create new notes, show a "new" link. +- -Configuration/Parameters - - -- Under OpenACS 4.5, parameters are set at two levels: at the global level by - the OpenACS-admin, and at the subsite level by a sub-admin. In this - section, list and discuss both levels of parameters. - ++ add-edit +This page is used show a form for editing notes, to show + a form for creating new notes, and to process both forms after + submission. ++ ++ +If a note id is passed in, make sure that the + current user has permission to edit that note. If not, + make sure that the current user has permission to create + new notes. ++ +Use the template system to generate a form for + editing/creating a note. If an existing note id was + passed in, populate the form fields wih that note's + values. + +- -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 analysis" - section can greatly facilitate the documenting of this section. - -Index: openacs-4/packages/acs-core-docs/www/files/samplenote/page-map.dia =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/files/samplenote/Attic/page-map.dia,v diff -u -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/acs-core-docs/www/files/samplenote/page-map.dia 2 Apr 2003 17:58:03 -0000 1.1.2.1 +++ openacs-4/packages/acs-core-docs/www/files/samplenote/page-map.dia 7 Apr 2003 17:00:22 -0000 1.1.2.2 @@ -1,11 +1,7 @@ - � ��r�0��y -�l��0$�3��E;�4k� ���m�g/��6dž�E*��3h���#�p>k|�����F,�4��:�d �> -p ��_�n �a~u `x��C#)�F��W3y�yr�����] -9e��H���,H��W�t(@�jrΰ��H�a�f��?!��8�˨*Χ�2i -�L�~.^�ZɨG:'�� V����,��FH�N�ySE�YP ί����-U{���4�d!��> ARN� �0^��r o| 2�����2� �M�R�`\:q�B�}R �l˜JE���9�o��3$�9 �ï�si%� � �(�Ce��\lG��R}7����#���q��M~7P~�:�p��7V�8�CiY��o%^�;7�r�֤ - w�U�_��I��*��Y��o��*���?�����6�8�ɏ�����ɤ�GOcv���S`*S0��7��K����,�W��XL���Nׁi����� "(Z����&�n) E�6�z)\h�k�_" .y���~� m�����t5�?��j��� m�I��x�t��6�|� -���q���R�ܩ� -�� .B ���k۪.05�Q `�ì -�m3;_�x -3�#�#ԾN(^E-��T�i{�^��S���֮o�rC���m�!O����jS�dߒ��s���q���Ё>��Fݜ��pQ�/�fQ�cyD+�qB��P�4����x�+��4+�0� 禮� e�3�n@N�ێ�� �`��^2� S��m -�x'�N���;�w�xg �;�F�[Ƙ��y����q��`b� �1�n`N� �4����� -0'xC��n��i+��<�x�� ���G��`ě �� /����\`��1�����<Ay剃���纶8��'0O`���O�y�u���� ��W� *A���. \ No newline at end of file + � �K��6���)\�+#,��w��C*�M�a�gJ�P"$"��%�=�l��{�j�f����%����?}�-���"#��m ��,�)a�����^"����SJ��;hi�+X��� )W ���v �>C� @�dx�/� +��О
