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). 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.

To answer this question, we should examine how OpenACS servers were organized in the past. We will assume throughout this document that the page root for your server is called ROOT. In OpenACS 3.2.x and earlier, a typical server might have a file system behind it that looked something like this:

ROOT/
   bin/
   parameters/
        ad.ini
     tcl/
        core tcl libraries here
     www/
         admin/
             forums/
                 site wide admin for forums
             intranet/
                 site wide admin for intranet

             ... and so on for all modules ...

         forums/
             pages for forums
             admin/
                 other admin pages for forums
         intranet/
             pages for intranet
             admin/
                 other admin pages for intranet
         doc/
             documentation
             sql/
                core and application data models here

         ... and so on for all modules ... 

In previous versions of OpenACS, you wrote a new application like this:

This structure is very simple, and worked well in a world where OpenACS was basically a single monolithic entity. But, this organization made it difficult to distribute modules as independent packages, because the pieces of each module are strewn all over the tree in at least 3 or 4 different areas.

Here is how an OpenACS 5.2.0d1 server is laid out:

ROOT/
    bin/
    packages/
        acs-admin/
        acs-api-browser/
        acs-content-repository/
        acs-core-docs/
        acs-developer-support/
        acs-kernel/
        acs-ldap-authentication/
        acs-messaging/
        acs-subsite/
        acs-templating/
        acs-test-harness/
        acs-util/
        acs-workflow/
        forums/
               forums.info
               catalog/
                    i18n message catalogs
               lib/
		    includable page fragments (.tcl/.adp pairs)
               sql/
                    oracle/
                         oracle data model
                    postgresql/
                         postgresql data model
               tcl/
                    tcl library code
               www/
                    user visible pages
                    admin/
                         administration pages
                    doc/
                         documentation
        message-catalog/
        news/
        notification/
        page/
    tcl/
            bootstrap code
    www/
            misc pages

Note that a major reorganization has happened here. The diagram only expands the structure of the forums/ package directory, but all the others are basically the same. 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 organization has two major advantages:

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.2.0d1, this tool is called the APM.

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:

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 new site management features in OpenACS 5.2.0d1 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.

To illustrate the general structure of a package, let's see what the package for the "notes" application should look like. This is shown in the diagram below:

ROOT/
  +-- packages/    APM Root
        |
        +-- notes/  Package Root 
        |     |
        |     |
        |     +-- 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
        |     +-- 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.tcl                   Documentation Index Page
        |     |     |     +-- ...                         Administration Pages
        |     |     +-- 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
        |     +-- notes.info                              Package Specification File
        +-- 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.

Here is how you make a package.

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. This process is slightly more complex than in OpenACS 3.x, but also much more flexible.

In OpenACS 3.x, everything in the site was implicitly mounted underneath ROOT/www. AOLserver automatically took any URL like /foo/bar/moo/baz.html and mapped it to the file ROOT/www/foo/bar/moo/baz.html. This was conveniently simple, but lacked flexibility. In particular, it was difficult to map content that lived outside the page root into the site, and it was also hard to map mulitiple URLs to the same place in the file system.

In OpenACS 5.2.0d1, 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 notes-1.

Then type this URL into your browser:

http://your-server.your-domain.com/notes/hello.html

    

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: