Creating an Application Package

by Joel Aufrecht

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

The intended page map

Overview

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 with user interface is called an application; a package which provides functions to other packages and has no direct interface, a service. 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 writing documentation, setting up database tables and procedures, writing web pages, debugging, and automatic regression testing.

This tutorial uses the content repository package. This radically simplifies the database work, but forces us to work around the content repository's limitations, including an incomplete Tcl API. So the tutorial is messier than we'd like right now. Code that is temporary hackage is clearly marked.

In this tutorial, we will make an application package for displaying a list of text notes.

Before you begin

You will need:

  • A computer with a working installation of OpenACS. If you don't have this, see Chapter 2, Installation Overview.

  • Example files, which are included in the standard OpenACS 5.9.0 distribution.

Figure 9.1. Assumptions in this section

Fully qualified domain name of your serveryourserver.test
URL of your serverhttp://yourserver.test:8000
Name of development account$OPENACS_SERVICE_NAME
New Package keymyfirstpackage

Use the APM to initialize a new package

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, myfirstpackage. This will create the initial directories, meta-information files, and database entries for a new package. (More info on APM)

  1. Browse to http://yourserver:8000/acs-admin/apm.

  2. Click Create a New Package.

    Fill in the fields listed below. Ignore the rest (and leave the check boxes alone). (Some will change automatically. Don't mess with those.)

    • Package Key: myfirstpackage

    • Package Name: My First Package

    • Package Plural: My First Package

    • Package Type: Application

    • Initial Version: 0.1d

    • Summary: This is my first package.

    At the bottom, click Create Package.

This creates a package rooted at /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage. This is the "home directory" of our new package, and all files in the package will be within this directory. More on the structure of packages).

Add an Application Instance to the Server

In order to see your work in progress, you must create a map between the URL space of incoming requests and the package application instance. You do this by adding the application in the main site administration). This creates a link between the incoming URL requests and an instance of the application. (More on applications and nodes)

You can have 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.

  1. Browse to http://yourserver.test:8000/admin/applications/application-add/.

  2. Choose "My First Package" from the list and click OK (the other fields are optional).

By mounting the package, we've caused all requests to http://yourserver.test:8000/myfirstpackage to be satisfied from the files at /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www.

Quick start

The remainder of the tutorial walks you through each file one at a time as you create the package. You can skip all this, and get a working package, by doing the following:

cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/tutorial
psql $OPENACS_SERVICE_NAME -f myfirstpackage-create.sql
cp note-edit.* note-delete.tcl index.* ../../../../myfirstpackage/www/
mkdir ../../../../myfirstpackage/lib
cp note-list.* ../../../../myfirstpackage/lib/
cp myfirstpackage-*sql ../../../../myfirstpackage/sql/postgresql/
cp myfirstpackage-procs.tcl ../../../../myfirstpackage/tcl/test/
cp note-procs.tcl ../../../../myfirstpackage/tcl/

After restarting the server, the tutorial application will be installed and working at the url you selected in the previous step.