| Prev | Chapter�10.�Development Reference | Next |
|---|
By Pete Su and Bryan Quinn
+ +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 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�10.1.�Server file layout diagram
+
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 means developers can track down @@ -46,12 +46,12 @@ 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. + 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
+ 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/resources
+ PACKAGE-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�10.1.�Package files
| File Type | Its Use | Naming Convention | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Package Specification File | The package specification file is an XML file generated and
+ Table 10.1. Package files
| www/*.adp | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| UI Index Page | The UI must have an index page composed of a logic script
+ called index.tcl and a template called
+ index.adp. | www/index.tcl |
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 - libraries, and so on.
Checking what packages depend on what other packages.
Storing information on the package including ownership and a file +
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.
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 @@ -237,12 +253,12 @@
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. -
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 +
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
everything means, but we'll repeat the important bits here for easy
reference:
@@ -252,27 +268,27 @@
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
- package keys in the current system include: forums,
- acs-kernel and so on. For the example application, we
- will use the package key notes.
+ package keys in the current system include: forums,
+ acs-kernel and so on. For the example application, we
+ will use the package key notes.
This is a short human readable name for your package. For our example, - we will use the name "Notes". + we will use the name "Notes".
If your package name is a nice singular noun, this should be the plural form of it. I assume the plural form is used when multiple instances of the package are used by a single service. We'll talk more about package instances later. Our example apllication doesn't really - have a good plural name. So just make it also be "Notes". + have a good plural name. So just make it also be "Notes".
Generally we think of packages as either being applications,
meaning that the package is meant primarily for use by end-users, or
services meaning that the package is meant to be a reusable
- library of code, to be used by other packages. forums is
- a good example of an application, while acs-templating is
+ library of code, to be used by other packages. forums is
+ a good example of an application, while acs-templating is
a good example of a service. Our example is an application, so pick
that.
Enter a short summary and longer description of what the Notes - application will do. That is, something like "this application keeps - short textual notes in the database", and so on. + application will do. That is, something like "this application keeps + short textual notes in the database", and so on.
-
Click the button "Create Package". -
At this point, APM will create a directory called - ROOT/packages/notes. -
+
Click the button "Create Package". +
At this point, APM will create a directory called
+ ROOT/packages/notes.
+
The directory that APM created will be empty except for the
- notes.info file. Create a file
+ notes.info file. Create a file
called
- ROOT/packages/notes/sql/oracle/notes-create.sql. We'll
- fill this file with our data model
+ ROOT/packages/notes/sql/oracle/notes-create.sql. We'll
+ fill this file with our data model
very soon. Create a file called
- ROOT/packages/notes/sql/oracle/notes-drop.sql. This
+ ROOT/packages/notes/sql/oracle/notes-drop.sql. This
will contain the instructions to drop the data model. To be
complete, you would also create the PostgreSQL versions of these
files as well in
- ROOT/packages/notes/sql/postgresql/notes-create.sql
+ ROOT/packages/notes/sql/postgresql/notes-create.sql
and
- ROOT/packages/notes/sql/postgresql/notes-drop.sql.
+ 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
+ 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
that lists all the files you just added and lets you add them to
- the notes package.
+ the notes package.
- Note that while the .sql files
+ Note that while the .sql files
have been added to the packge, they have not
been loaded into the database. For the purposes of development,
you have to load the data model by hand, because while OpenACS
has automatic mechanisms for loading and reloading
- .tcl files for code, it does not
+ .tcl files for code, it does not
do the same thing for data model files.
-
Now go back to the main management page for the notes - If your package has parameters, create them using the "Manage - Parameter Information" link. Define package callbacks via the "Tcl Callbacks (install, - instantiate, mount)" link.
The new package has been created and installed in the server. At +
Now go back to the main management page for the notes
+ If your package has parameters, create them using the "Manage
+ Parameter Information" link. Define package callbacks via the "Tcl Callbacks (install,
+ instantiate, mount)" link.
The new package has been created and installed in the server. At this point, you should add your package files to your CVS repository. 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: + this appendix. If so, then you just do this:
% cd ROOT/packages % cvs add notes % cd notes @@ -342,18 +358,18 @@ % cd sql % cvs add *.sql % cd ROOT/packages/notes -% cvs commit -m "add new package for 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. -
+ 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
- ROOT/packages/notes/www directory. So go there and add a
- file called hello.html with some text in it. Now we have
+ 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
+ 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.
@@ -366,49 +382,49 @@
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
+ 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
+ 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
+ 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
+ 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.
+ 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://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
+ 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
+ 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.
-
+ 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. -
+
Manages package upgrades. -
+
Manages information on all package instances in a site. For correctly written application packages, this allows the site administrator to map multiple instances of a package to URLs within a site. -
+
Writes out package distribution files for other people to download and install. We'll cover this later. -