- I OpenACS For Everyone
- I.1 High level information: What is OpenACS?
- I.1.1 Overview
- I.1.2 OpenACS Release Notes
- I.2 OpenACS: robust web development framework
- I.2.1 Introduction
- I.2.2 Basic infrastructure
- I.2.3 Advanced infrastructure
- I.2.4 Domain level tools
- I.1 High level information: What is OpenACS?
- II Administrator's Guide
- II.2 Installation Overview
- II.2.1 Basic Steps
- II.2.2 Prerequisite Software
- II.3 Complete Installation
- II.3.1 Install a Unix-like system and supporting software
- II.3.2 Install Oracle 10g XE on debian
- II.3.2.1 Install Oracle 8.1.7
- II.3.3 Install PostgreSQL
- II.3.4 Install AOLserver 4
- II.3.5 Quick Install of OpenACS
- II.3.5.1 Complex Install OpenACS 5.3
- II.3.6 OpenACS Installation Guide for Windows2000
- II.3.7 OpenACS Installation Guide for Mac OS X
- II.4 Configuring a new OpenACS Site
- II.4.1 Installing OpenACS packages
- II.4.2 Mounting OpenACS packages
- II.4.3 Configuring an OpenACS package
- II.4.4 Setting Permissions on an OpenACS package
- II.4.5 How Do I?
- II.4.6 Configure OpenACS look and feel with templates
- II.5 Upgrading
- II.5.1 Overview
- II.5.2 Upgrading 4.5 or higher to 4.6.3
- II.5.3 Upgrading OpenACS 4.6.3 to 5.0
- II.5.4 Upgrading an OpenACS 5.0.0 or greater installation
- II.5.5 Upgrading the OpenACS files
- II.5.6 Upgrading Platform components
- II.6 Production Environments
- II.6.1 Starting and Stopping an OpenACS instance.
- II.6.2 AOLserver keepalive with inittab
- II.6.3 Running multiple services on one machine
- II.6.4 High Availability/High Performance Configurations
- II.6.5 Staged Deployment for Production Networks
- II.6.6 Installing SSL Support for an OpenACS service
- II.6.7 Set up Log Analysis Reports
- II.6.8 External uptime validation
- II.6.9 Diagnosing Performance Problems
- II.7 Database Management
- II.7.1 Running a PostgreSQL database on another server
- II.7.2 Deleting a tablespace
- II.7.3 Vacuum Postgres nightly
- II.8 Backup and Recovery
- II.8.1 Backup Strategy
- II.8.2 Manual backup and recovery
- II.8.3 Automated Backup
- II.8.4 Using CVS for backup-recovery
- II.A Install Red Hat 8/9
- II.B Install additional supporting software
- II.B.1 Unpack the OpenACS tarball
- II.B.2 Initialize CVS (OPTIONAL)
- II.B.3 Add PSGML commands to emacs init file (OPTIONAL)
- II.B.4 Install Daemontools (OPTIONAL)
- II.B.5 Install qmail (OPTIONAL)
- II.B.6 Install Analog web file analyzer
- II.B.7 Install nspam
- II.B.8 Install Full Text Search
- II.B.9 Install Full Text Search using Tsearch2
- II.B.10 Install Full Text Search using OpenFTS (deprecated see tsearch2)
- II.B.11 Install nsopenssl
- II.B.12 Install tclwebtest.
- II.B.13 Install PHP for use in AOLserver
- II.B.14 Install Squirrelmail for use as a webmail system for OpenACS
- II.B.15 Install PAM Radius for use as external authentication
- II.B.16 Install LDAP for use as external authentication
- II.B.17 Install AOLserver 3.3oacs1
- II.C Credits
- II.C.1 Where did this document come from?
- II.C.2 Linux Install Guides
- II.C.3 Security Information
- II.C.4 Resources
- II.2 Installation Overview
- III For OpenACS Package Developers
- III.9 Development Tutorial
- III.9.1 Creating an Application Package
- III.9.2 Setting Up Database Objects
- III.9.3 Creating Web Pages
- III.9.4 Debugging and Automated Testing
- III.10 Advanced Topics
- III.10.1 Write the Requirements and Design Specs
- III.10.2 Add the new package to CVS
- III.10.3 OpenACS Edit This Page Templates
- III.10.4 Adding Comments
- III.10.5 Admin Pages
- III.10.6 Categories
- III.10.7 Profile your code
- III.10.8 Prepare the package for distribution.
- III.10.9 Distributing upgrades of your package
- III.10.10 Notifications
- III.10.11 Hierarchical data
- III.10.12 Using .vuh files for pretty urls
- III.10.13 Laying out a page with CSS instead of tables
- III.10.14 Sending HTML email from your application
- III.10.15 Basic Caching
- III.10.16 Scheduled Procedures
- III.10.17 Enabling WYSIWYG
- III.10.18 Adding in parameters for your package
- III.10.19 Writing upgrade scripts
- III.10.20 Connect to a second database
- III.10.21 Future Topics
- III.11 Development Reference
- III.11.1 OpenACS Packages
- III.11.2 OpenACS Data Models and the Object System
- III.11.3 The Request Processor
- III.11.4 The OpenACS Database Access API
- III.11.5 Using Templates in OpenACS
- III.11.6 Groups, Context, Permissions
- III.11.7 Writing OpenACS Application Pages
- III.11.8 Parties in OpenACS
- III.11.9 OpenACS Permissions Tediously Explained
- III.11.10 Object Identity
- III.11.11 Programming with AOLserver
- III.11.12 Using Form Builder: building html forms dynamically
- III.12 Engineering Standards
- III.12.1 OpenACS Style Guide
- III.12.2 Release Version Numbering
- III.12.3 Constraint naming standard
- III.12.4 ACS File Naming and Formatting Standards
- III.12.5 PL/SQL Standards
- III.12.6 Variables
- III.12.7 Automated Testing
- III.13 CVS Guidelines
- III.13.1 Using CVS with OpenACS
- III.13.2 OpenACS CVS Concepts
- III.13.3 Contributing code back to OpenACS
- III.13.4 Additional Resources for CVS
- III.14 Documentation Standards
- III.14.1 OpenACS Documentation Guide
- III.14.2 Using PSGML mode in Emacs
- III.14.3 Using nXML mode in Emacs
- III.14.4 Detailed Design Documentation Template
- III.14.5 System/Application Requirements Template
- III.15 TCLWebtest
- III.16 Internationalization
- III.16.1 Internationalization and Localization Overview
- III.16.2 How Internationalization/Localization works in OpenACS
- III.16.4 Design Notes
- III.16.5 Translator's Guide
- III.D Using CVS with an OpenACS Site
- III.9 Development Tutorial
- IV For OpenACS Platform Developers
- IV.17 Kernel Documentation
- IV.17.1 Overview
- IV.17.2 Object Model Requirements
- IV.17.3 Object Model Design
- IV.17.4 Permissions Requirements
- IV.17.5 Permissions Design
- IV.17.6 Groups Requirements
- IV.17.7 Groups Design
- IV.17.8 Subsites Requirements
- IV.17.9 Subsites Design Document
- IV.17.10 Package Manager Requirements
- IV.17.11 Package Manager Design
- IV.17.12 Database Access API
- IV.17.13 OpenACS Internationalization Requirements
- IV.17.14 Security Requirements
- IV.17.15 Security Design
- IV.17.16 Security Notes
- IV.17.17 Request Processor Requirements
- IV.17.18 Request Processor Design
- IV.17.19 Documenting Tcl Files: Page Contracts and Libraries
- IV.17.20 Bootstrapping OpenACS
- IV.17.21 External Authentication Requirements
- IV.18 Releasing OpenACS
- IV.18.1 OpenACS Core and .LRN
- IV.18.2 How to Update the OpenACS.org repository
- IV.18.3 How to package and release an OpenACS Package
- IV.18.4 How to Update the translations
- IV.17 Kernel Documentation
- V Tcl for Web Nerds
- V.1 Tcl for Web Nerds Introduction
- V.2 Basic String Operations
- V.3 List Operations
- V.4 Pattern matching
- V.5 Array Operations
- V.6 Numbers
- V.7 Control Structure
- V.8 Scope, Upvar and Uplevel
- V.9 File Operations
- V.10 Eval
- V.11 Exec
- V.12 Tcl for Web Use
- V.13 OpenACS conventions for TCL
- V.14 Solutions
- VI SQL for Web Nerds
- VI.1 SQL Tutorial
- VI.1.1 SQL Tutorial
- VI.1.2 Answers
- VI.2 SQL for Web Nerds Introduction
- VI.3 Data modeling
- VI.3.1 The Discussion Forum -- philg's personal odyssey
- VI.3.2 Data Types (Oracle)
- VI.3.4 Tables
- VI.3.5 Constraints
- VI.4 Simple queries
- VI.5 More complex queries
- VI.6 Transactions
- VI.7 Triggers
- VI.8 Views
- VI.9 Style
- VI.10 Escaping to the procedural world
- VI.11 Trees
- VI.1 SQL Tutorial
III.11.1 OpenACS Packages
This document is a guide on how to write a software package for OpenACS. OpenACS packages are installed and maintained with the OpenACS Package Manager (APM) which is part of the acs-admin package. This document presents reasons for packaging software, conventions for the file system and naming that must be followed, and step by step instructions for creating a new package for the "Notes" example package.
Here is how an OpenACS 5 server is laid out starting from the Server root (ROOT):
Figure11.1.Server file layout diagram
ROOT/ bin/ Various executables and scripts for server maintanence. content-repository-content-files/ content repository content stored in the filesystem. etc/ Installation scripts and configuration files. packages/ acs-admin/ acs-api-browser/ ... many many more... workflow/ log/ Server error and access logs tcl/ bootstrap code www/ Pages not in packages (static content, customized pages)
Each package encapsulates all of its data model, library code, logic, adminstration pages and user pages in a single part of the file tree. This means developers can track down everything that is related to a particular package without hunting all over the file system. Encapsulating everything about a package in one place also makes it much easier to distribute packages independently from the OpenACS Core.
In order to make this work, we need a system that keeps track of the packages that have been installed in the server, where those packages have been installed, and a standard way to map URLs that a client sends to our server to the right page in the appropriate package. While we're at it, this tool should also automate package installation, dependency checking, upgrades, and package removal. In OpenACS 5, this tool is called the APM.
To illustrate the general structure of a package, let's see what the package for the "notes" application should look like.
Figure11.2.Package file layout diagram
ROOT/ +-- packages/ APM Root | +-- notes/ Package Root | | | +-- notes.info Package Specification File | +-- sql/ | | | | | +-- oracle/ | | | | | | | +-- notes-create.sql Data Model Creation Script for Oracle | | | +-- notes-drop.sql Data Model Drop Script | | | +-- *.sql Data Model Files | | | +-- upgrade/ | | | +-- upgrade-4.1-4.5.sql Data Model Upgrade Scripts | | +-- postgresql/ | | | | | | | +-- notes-create.sql Data Model Creation Script for PostgreSQL | | | +-- notes-drop.sql Data Model Drop Script | | | +-- *.sql Data Model Files | | | +-- upgrade/ | | | +-- upgrade-4.1-4.5.sql Data Model Upgrade Scripts | +-- tcl/ | | | | | +-- notes-procs.tcl Tcl Library | | +-- notes-procs.xql SQL92 Queries for notes-procs.tcl | | +-- notes-procs-oracle.xql Oracle-specific queries for notes-procs.tcl | | +-- notes-procs-postgresql.xql PostgreSQL-specific Queries for notes-procs.tcl | | +-- notes-init.tcl Tcl Initialization | | +-- notes-init.xql Queries for notes-init.tcl (work in all DBs) | | +-- *.tcl Tcl Library Files | +-- lib/ | | | | | +-- *.tcl Includable page logic | | +-- *.adp Includable page templates | +-- www/ | | | | | +-- admin/ Administration UI | | | +-- tests/ Regression Tests | | | | +-- index.tcl Regression Test Index Page | | | | +-- ... Regression Tests | | | +-- index.tcl Administration UI Index Page | | | +-- ... Administration UI Pages | | | | | +-- doc/ Documentation | | | +-- index.html Documentation Index Page | | | +-- ... Administration Pages | | +-- resources/ Static Content | | | +-- ... Static Content files | | +-- index.tcl UI Index Page | | +-- index.adp UI Index Template | | +-- index.xql Queries for UI Index page | | +-- *.tcl UI Logic Scripts | | +-- *.adp UI Templates | | +-- *-oracle.xql Oracle-specific Queries | | +-- *-postgresql.xql PostgreSQL-specific Queries +-- Other package directories.
All file locations are relative to the package root, which in this case is
ROOT/packages/notes. The following table describes in detail what each of the files up in the diagram contain.
A special note on the
PACKAGE-KEY/www/resources directory. Files in this directory are available at
|File Type||Its Use||Naming Convention|
|Package Specification File||The package specification file is an XML file generated and maintained by the OpenACS Package Manager (APM). It specifies information about the package including its parameters and its files.||
|Data Model Creation Script||Contains the SQL that creates the necessary data model and PL/SQL packages (or PL/pgSQL or whatever) to support the package. The name must match the convention below or the package will not be installed correctly. Notice that the script must be under the appropriate directory for the database you are developing your package for (hopefully all OpenACS-supported databases :-))||
|Data Model Drop Script||Contains the SQL that removes the data model and PL/SQL packages generated by the creation script. The name must match the convention below or the package will not be installed correctly.||
|Data Model File||Any .sql file that does not match the naming convention above is recognized as a data model file. It is useful to separate the SQL in the creation and drop scripts into several files and then have the scripts source the other data model files. In Oracle this can be done by including @@ filename in the creation or drop scripts. See the Oracle FAQ for examples. In PostgreSQL the same is acomplished by including \i filename.||
|Data Model Upgrade Scripts||Contain changes to the data model between versions. The APM can automatically load the appropriate upgrade scripts when upgrading to a new version of a package.||
|SQL92 Query Files||Files with queries that are supported by all databases. These are usually SQL92 queries. Notice that the .xql filename must match the name of the .tcl file that uses those queries.||
|Oracle-specific Query Files||Files with queries that are Oracle-specific. Notice that the .xql filename must match the name of the .tcl file that uses those queries.||
|PostgreSQL-specific Query Files||Files with queries that are PostgreSQL-specific. Notice that the .xql filename must match the name of the .tcl file that uses those queries.||
|Tcl Library Files||The Tcl library files include a set of procedures that provide an application programming interface (API) for the package to utilize.||
|Tcl Initialization||The initialization files are used to run Tcl procedures that should only be sourced once on startup. Examples of statements to put here are registered filters or procedures. Tcl initialization files are sourced once on server startup after all of the Tcl library files are sourced.||
|Administration UI||The administration UI is used to administer the instances of the package. For example, the forums administration UI is used to create new forums, moderate postings, and create new categories for forums postings.||
|Administration UI Index Page||Every package administration UI must have an index page. In most cases, this is
|Regression Tests||Every package should have a set of regression tests that verify that it is in working operation. These tests should be able to be run at any time after the package has been installed and report helpful error messages when there is a fault in the system.||
|Regression Test Index Page||The regression test directory must have an index page that displays all of the tests available and provides information on how to run them. This file can have any extension, as long as its name is
|Documentation||Every package must include a full set of documentation that includes requirements and design documents, and user-level and developer-level documentation where appropriate.||
|Documentation Index Page||The documentation directory must include a static HTML file with the name of
|UI Logic Scripts||Packages provide a UI for users to access the system. The UI is split into Logic and Templates. The logic scripts perform database queries and prepare variables for presentation by the associated templates.||
|UI Templates||Templates are used to control the presentation of the UI. Templates receive a set of data sources from the logic scripts and prepare them for display to the browser.||
|UI Index Page||The UI must have an index page composed of a logic script called
The APM is used to create, maintain, and install packages. It takes care of copying all of the files and registering the package in the system. The APM is responsible for:
Automatic installation of packages: loading data models, code libraries, and so on.
Checking what packages depend on what other packages.
Storing information on the package including ownership and a file list.
In addition for packages that are applications, the APM is responsible for keeping track of where in the site a user must go in order to use the application. To do this, the APM defines a set of objects that we call package instances. Once a package is loaded, the administrator can create as many instances of the package as she likes, and map these instances to any URL in the site that she wants. If packages are analogous to executable programs in an operating system, then package instances are analgous to multiple running copies of a single program. Each instance can be independently administered and each instance maintains its own set of application parameters and options.
The following sections will show you how to make a package for the Notes application. In addition, they will discuss some site management features in OpenACS 5 that take advantage of the APM's package instance model. The two most important of these are subsites, and the site map tool, which can be used to map applications to one or more arbitrary URLs in a running site.
We will also discuss how to organize your files and queries so they work with the OpenACS Query Dispatcher.
Here is how you make a package.
Login as a site-wide administrator on your web service.
Go to the package manager on your server. The URL is /acs-admin/apm.
Click on the link /acs-admin/apm/package-add.
Fill out the form for adding a new package. The form explains what everything means, but we'll repeat the important bits here for easy reference:
- Package Key
This is a short text string that should uniquely name your package to distinguish it from all the others. It is used as a database key to keep track of the package and as the name of the directory in the file system where all the files related to your package will live. Example package keys in the current system include:
acs-kerneland so on. For the example application, we will use the package key
- Package Name
This is a short human readable name for your package. For our example, we will use the name "Notes".
- Package Plural
If your package name is a nice singular noun, this should be the plural form of it. I assume the plural form is used when multiple instances of the package are used by a single service. We'll talk more about package instances later. Our example apllication doesn't really have a good plural name. So just make it also be "Notes".
- Package Type
Generally we think of packages as either being applications, meaning that the package is meant primarily for use by end-users, or services meaning that the package is meant to be a reusable library of code, to be used by other packages.
forumsis a good example of an application, while
acs-templatingis a good example of a service. Our example is an application, so pick that.
- Package URL
The URL from which people will download your package when it is done. Just use the default for this, you can change it later.
- Initial Version
Just use the default here, which by convention is 0.1d.
- Version URL
Just use the default here.
- Summary and Description
Enter a short summary and longer description of what the Notes application will do. That is, something like "this application keeps short textual notes in the database", and so on.
Click the button "Create Package".
At this point, APM will create a directory called
The directory that APM created will be empty except for the
notes.infofile. Create a file called
ROOT/packages/notes/sql/oracle/notes-create.sql. We'll fill this file with our data model very soon. Create a file called
ROOT/packages/notes/sql/oracle/notes-drop.sql. This will contain the instructions to drop the data model. To be complete, you would also create the PostgreSQL versions of these files as well in
After you do this, go back to the main APM page. From there, click the link called "notes" to go to the management page for the new package. Now click the link called "Manage file information", then the "Scan the
packages/notesdirectory for additional files in this package" link on that page to scan the file system for new files. This will bring you do a page that lists all the files you just added and lets you add them to the
Note that while the
.sqlfiles have been added to the packge, they have not been loaded into the database. For the purposes of development, you have to load the data model by hand, because while OpenACS has automatic mechanisms for loading and reloading
.tclfiles for code, it does not do the same thing for data model files.
Now go back to the main management page for the
notesIf your package has parameters, create them using the "Manage Parameter Information" link. Define package callbacks via the "Tcl Callbacks (install, instantiate, mount)" link.
The new package has been created and installed in the server. At this point, you should add your package files to your CVS repository. I'll assume that you have set up your development repository according to the standards described in this appendix. If so, then you just do this:
% cd ROOT/packages % cvs add notes % cd notes % cvs add notes.info % cvs add sql % cd sql % cvs add *.sql % cd ROOT/packages/notes % cvs commit -m "add new package for notes"
Now you can start developing the package. In addition to writing code, you should also consider the tasks outlined in the package development tutorial.
At this point, you are probably excited to see your new package in action. But, we haven't added any user visible pages yet. By convention, user visible pages go in the
ROOT/packages/notes/www directory. So go there and add a file called
hello.html with some text in it. Now we have to make the user pages visible in the site. Since we didn't put the pages underneath
ROOT/www they will not appear on their own. What we have to do is mount the application into the site map. That is, we have to define the URL from which the application will serve its pages.
In OpenACS 5, administrators can define an arbitrary mapping between the URLs the user types and the actual file in the file system that is served. This mapping is called the site map and entries in the site map are called site nodes. Each site node maps a URL to an OpenACS object. Since package instances are objects, the site map allows us to easily map package instances to URLs. As we said before, each instance of an application has its own set of parameters and runs from its own URL within the site. What this means is that even though all the code for the
notes application lives in
ROOT/packages/notes, the application itself can run from any number of locations in the site. This allows developers and administrators to build sites that look to the user like a collection of many indedendent applications that actually run on a single shared code base. The request-processor document shows you how OpenACS figures out which instance of your application was requested by the user at any given time. The page development tutorial shows you how to use this information in your user interface.
In order to make the new
notes application visible to users, we have to mount it in the site map. You do this by going to the Site Map page, which is by default available at
/acs-admin/site-map. Use the interface here to add a new sub-folder called
notes to the root of the site, then click "new application" to mount a new instance of the
notes application to the site. Name the new instance
Then type this URL into your browser:
Now you should see the contents of the page that you added. What has happened is that all URLs that start with
/notes have been mapped in such a way as to serve content from the directory
ROOT/packages/notes/www. At this point, you can experiment with the site map by mounting multiple instances of the not yet written Notes application at various places in the site. In a later document, we'll see how to write your application so that the code can detect from what URL it was invoked. This is the key to supporting subsites.
The APM performs the following tasks in an OpenACS site:
Manages creation, installation, and removal of packages from the server. Also keeps track of what files belong to which packages.
Manages package upgrades.
Manages information on all package instances in a site. For correctly written application packages, this allows the site administrator to map multiple instances of a package to URLs within a site.
Writes out package distribution files for other people to download and install. We'll cover this later.