| Prev | Chapter 11. Development Reference | Next |
|---|
By Pete Su and Bryan Quinn
- </authorblurb> - -+
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 + conventions for the filesystem 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): -
-Figure 11.1. Server file layout diagram
- - -Each package encapsulates all of its data model, library code, logic, administration 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 + package without hunting all over the filesystem. 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. -
- -
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/resourcesPACKAGE-KEY/www/resources
directory.
Files in this directory are available at
- http://
+ yourserver/resources/PACKAGE-KEY/...http://yourserver/resources/PACKAGE-KEY/...
and are returned without any permissions checking or even checks
that the package is installed or mounted. Files are returned
directly, so .tcl or .adp files are not sourced in these
directories. This makes it suitable for storing icons, css
files, javascript, and other static content which can be treated
this way.
-
Table 11.1. Package files
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: -
- -Package registration
Automatic installation of packages: loading data models, code +
Package registration
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.
+ 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 + operating system, then package instances are analogous 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. +
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 @@ -333,8 +266,7 @@
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
+ keep track of the package and as the name of the directory in the filesystem where all the files related to your package will live. Example
package keys in the current system include: forums,
acs-kernel and so on. For the example application, we
will use the package key notes.
@@ -391,21 +323,17 @@
ROOT/packages/notes/sql/postgresql/notes-create.sql
and
ROOT/packages/notes/sql/postgresql/notes-drop.sql.
-
+
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/notes directory 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
+ the filesystem for new files. This will bring you to a page
that lists all the files you just added and lets you add them to
the notes package.
-
+
Note that while the .sql files
have been added to the package, they have not
been loaded into the database. For the purposes of development,
@@ -421,10 +349,7 @@
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 +% cd ROOT/packages % cvs add notes % cd notes % cvs add notes.info @@ -433,23 +358,10 @@ % 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 @@ -460,11 +372,9 @@ 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 + URLs the user types and the actual file in the filesystem 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 @@ -480,9 +390,7 @@ 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
@@ -491,13 +399,9 @@
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://
- yourserver/notes/hello.html
+
+ Then type this URL into your browser: http://yourserver/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
@@ -507,19 +411,9 @@
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.
@@ -532,18 +426,4 @@
Writes out package distribution files for other people to download and install. We'll cover this later. -
($Id$)
- -