OpenACS Packages

The first step in working with an APM package is to load it, which normally means copying it into the filesystem where your OpenACS system resides. If your OpenACS system is under /web/atf/, then all packages go under /web/atf/packages. (For this reason, each package needs a unique name; many OpenACS developers use an Emacs-style package naming convention, in which the package name is preceded by the developer or client name. This helps to avoid conflicts between the foo-attributes and the bar-attributes packages.) Copy the package's entire directory structure into /web/atf/packages, making sure the files and directories are readable (and writable) by the user ID under which AOLserver operates.

An easier and more reliable way to install APMs is to click on the load packages link within the package manager. OpenACS will ask you for the URL of the APM or the name of the directory in which one or more packages reside. OpenACS then will find all of the .apm files located there, unpack and load them into the system.

Once a package has been loaded into the filesystem, you must install its data model and register it with the system. This is done through the web-based package manager, which normally is found under the URL /acs-admin/apm on an OpenACS system. Typically, only the site administrator has access to the package manager.

The main package manager screen shows all of the packages that are loaded in the system and indicates whether each has been installed, superseded by a newer version or is yet to be installed. Using the menu options at the top of the page, you can ask to see different subsets of the packages on the system, including only those that you are personally responsible for developing and managing.

The package manager is the main way in which you create, modify, update and install packages:

To install a new package, click on the install packages link at the bottom of the page. The package manager will scan the packages directory for any new packages, allowing you to choose which packages should be installed. (When you first install OpenACS, no packages are installed, so this is a very long list.) Each package can depend on one or more other packages. If you try to install a package without its prerequisite dependencies already installed, the package manager will require confirmation before continuing.

The installer lets you decide whether you want to install a package's data model or also enable the package for use on the site. Personally, I always enable any package I install, but I'm sure there are reasons why you might not want to do this. After checking the appropriate boxes, click on the Next button, which installs the data model. Following this, you must restart the AOLserver, because many packages depend on Tcl libraries loaded into AOLserver at startup. Therefore, the packages will not work until the server has been restarted.

Once you have restarted AOLserver, go to the package manager and look at the list of enabled packages. All of the packages you loaded should be visible on this list. From here, you can modify the packages, load more packages or begin to turn the loaded packages into an actual web site. This process is known as mounting and is performed using the OpenACS site map. In one of the more confusing parts of OpenACS administration, the site map is not part of the site-wide administration page; rather, it is part of the main site administration page. In other words, you manage packages under /acs-admin/apm, but you manage the site map under /admin/site-map. There are some good reasons for this, but it tends to confuse people more than it helps them.

The site map tells OpenACS how to connect a URL to an application. For example, you might want the OpenACS bboard package to be under the /forum URL or the /bboard URL. In some cases, you actually might want to have it in both places. The site map allows you to do this by clicking the mouse.

To connect a package to a URL for the first time, click on the New subfolder link to the right of the / path. You are asked to name the URL under which the new application should be mounted. To install the bboard package under /forum, you would enter forum (without the leading slash).

If you stop here, you can treat the new subfolder as nothing more than a folder in which new folders and/or static documents are placed. But you also can click the New application link associated with this folder, choosing an installed application package and giving it a human-readable name that will be used in titlebars and headlines. So while you might put the forums under the /bboard URL, you might want to give it the name Discussion forums. This title cannot be changed all that easily, so give this process some thought.

The new application link creates a new package instance and then attaches it to the directory you have created. To make an alias to this application, you can create a new subfolder and then use the mount link. It took me a while to understand that mount lets you connect to existing application instances, while new application creates an entirely new instance. This makes more sense when you consider that unmounting an application (using the unmount link to the right of the pathname) does not delete it but makes it unreachable. To delete an instance of an application completely, you must click on the unmounted application link from the site map, and then click on the delete link next to the unmounted application.

Each instance of an application has its own permissions and its own parameters. I have found parameters to be a particularly useful part of OpenACS, in that they let me create an application once and use it many times, but give each instance its own configuration. Following the appropriate links on the site map, you can view or change the parameters associated with a package instance.