Creating OpenACS Packages

Reuven shows how to develop your own simple web/database application using APM.

Last month, we continued our exploration
of OpenACS by looking at how individual applications are packaged
together using APM (the ArsDigita Package Manager). Every OpenACS
application normally combines database tables with server-side
programs, which means that installing or upgrading a package is
more complicated than copying some files. As we saw last month, the
APM application makes it relatively easy to install a package and
then instantiate it under one or more URLs.

This is great if you care only about using existing APMs. But
most OpenACS installations will require new, custom packages that
have their own data models and programs. While it's theoretically
possible to develop OpenACS applications without APMs, doing so
makes it hard to distribute your software, track versions or
standardize your installation procedure.

This month, we cover how to develop our own simple
web/database application using APM. The final result is an
application that someone else can load into their OpenACS
system.

Creating the Skeleton Package

The first step in creating a new OpenACS application is
making a new skeleton package via the web-based APM program. By
default, this program is available only to the user with
administration rights to an OpenACS system, so you might need to
ask the administrator to modify the permissions when you begin your
development work.

On most OpenACS systems, you can launch the APM program via
the /acs-admin/apm/ URL. This program displays all of the installed
APMs, including each one's name, version and number of files it
includes. The file count normally includes .sql files (for creating
and removing database definitions), .tcl files (containing Tcl
program code), .adp files (for web templates similar to ASP or JSP)
and .xql files (containing SQL queries). However, an APM can
contain other files, including images, text files or even something
more unusual, such as Flash.

As we saw last month, we can use this screen as an entry
point to install, inspect and modify the packages on our system.
But if we go down to the bottom of this list and click the create a
new package link, we can begin the process of creating our own
application.

The initial “create a package” screen asks for a number of
parameters that will help APM create a .info file that describes
the package to the system. Assuming that we want to create a
“hello, world” application with a minimum amount of work, we can
fill in a small number of fields:

The package key should be atf-hello. There is no
namespace hierarchy for APMs, but most developers put their name
(or a similar identifying term) at the front of the package name to
avoid conflicts.

The package name can be Hello or anything else you
choose; it is used by developers to distinguish it from other
packages.

We are developing an application, not a
service.

Our version number is 0.1d, meaning that it's in
early stages of development.

You can fill out or ignore the summary and
description at your discretion. It's a good idea to fill these in
for actual applications, however.

When finished, ensure that the “write a package” specifier
box is checked, and click the “create package” button at the
bottom of the page. You will be taken to the management screen for
this particular package. If you look in the packages subdirectory
on the filesystem where your OpenACS toolkit was installed, you'll
see an atf-hello directory, containing an atf-hello.info file in
the correct XML format.

Create a Data Model

Now that OpenACS recognizes our package, we can get to work
designing the data model for our package. As all experienced
web/database developers know, designing the tables is the hard
part; once you know how they will work, creating the applications
that add, delete and modify that data is pretty easy.

Our application will give us a simple guest book, in which
visitors to the site can enter comments on our page. (OpenACS comes
with a more general and powerful facility for doing this on any
page on the site, but we will ignore this in the interest of
learning how to create a package.) Our data model will look like
this:

On a purely technical level, the previous table definition
probably looks reasonable to anyone who has worked with PostgreSQL
before. We set up posting_id as an integer primary key, user_id as
a foreign key, a timestamp field (containing date and time
information) and then a text field to contain the actual posting.
Notice how our table name begins with atf_hello, reflecting the
fact that it is in the atf-hello APM. Keeping table names
consistent with package names is a primitive form of namespace
management, but it works well enough if everyone sticks with it.

The above works under PostgreSQL but isn't guaranteed to work
with Oracle. Given that the OpenACS community prides itself on
working transparently with both databases, what should we do to
avoid alienating our high-end colleagues?

The answer is that when installing the atf-hello package, APM
looks for a file named sql/atf-hello-create.sql. If such a file
exists, it is assumed to work on all support databases. If not, APM
looks for subdirectories named postgresql and oracle and executes
atf-hello-create.sql in the appropriate directory. So if your
system uses PostgreSQL, the above SQL would be saved in a file
named sql/postgresql/atf-hello-create.sql. Official OpenACS
packages are supposed to work with both Oracle and PostgreSQL out
of the box, which means that it's rare to find a package that works
with only one brand or the other. (The examples in this month's
column are guaranteed to work only with PostgreSQL, although
porting them to Oracle should not be too difficult.)

OpenACS also allows us to create a cleanup script, named
sql/PACKAGE-drop.sql, that removes all the tables and stored
procedures that the create script defined. We thus create a file
named sql/postgresql/atf-hello-drop.sql.

APM knows how to create the data model when a package is
first installed, but not when you're doing development work. So to
install atf-hello into the database, you'll need to handle it
manually:

psql -f atf-hello-create.sql openacs4

Of course, this assumes that openacs4 is the name of your
OpenACS database, that the PostgreSQL server is running on the same
machine as the psql client and that your current user name has
access rights to that database.

The site is intended for simplification of a life to those who wishes to understand the rough financial world.
On a site the useful and interesting information which will help you to orient as much as possible quickly in the financial world. Portal Finans