| -Prev | -Chapter 4. OpenACS Developer's Guide | -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). 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. -
-To answer this question, we should examine how OpenACS servers were organized in the past. We will assume throughout this document that the page root for your server is called ROOT. In OpenACS 3.2.x and earlier, a typical server might have a file system behind it that looked something like this: -
-+ROOT/ bin/ @@ -82,29 +47,20 @@ ... and so on for all modules ... --+
In previous versions of OpenACS, you wrote a new application like this: -
-Put all Tcl library procedures under - server-root/tcl.
Put all User viewable content under - server-root/www.
Put all Admin content under /admin/package-key/. -
+
Put all Tcl library procedures under + server-root/tcl.
Put all User viewable content under + server-root/www.
Put all Admin content under /admin/package-key/. +
This structure is very simple, and worked well in a world where OpenACS was basically a single monolithic entity. But, this organization made it difficult to distribute modules as independent packages, because the pieces of each module are strewn all over the tree in at least 3 or 4 different areas. -
-+
Here is how an OpenACS 4.5 server is laid out: -
-+ROOT/ bin/ @@ -143,88 +99,62 @@ www/ misc pages --+
Note that a major reorganization has happened here. The diagram only expands the structure of the bboard/ package directory, but all the others are basically the same. 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 organization has two major advantages: -
-+
This structure makes it easy for developers to track down - everything that is related to a particular package without + everything that is related to a particular package without hunting all over the file system. -
+
Encapsulating everything about a package in one place also makes it much easier to distribute packages indepedently from the OpenACS itself. -
+
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 are at it, this tool may as well also automate package installation, depedency checking, upgrades, and package removal. In OpenACS 4.5, this tool is called APM. -
-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 - list.
+
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 the application. To do this, the APM defines a set of objects that we - call package instances. Once a package is loaded, the + 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 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 new site management features in OpenACS 4.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 + 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 OpenACS' Query Dispatcher. -
-To illustrate the general structure of a package, let's see what the package for the "notes" application should look like. This is shown in the diagram below: -
-+ROOT/ +-- packages/ APM Root @@ -275,321 +205,178 @@ | +-- notes.info Package Specification File +-- Other package directories. --+
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. -
-| File Type | -Its Use | -Naming Convention | -||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Data Model Creation Script | -
+
| notes.info |
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: -
+
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 package keys in the current system include: bboard, 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". -
+
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". -
- Generally we think of packages as either being applications, +
+ 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 + services meaning that the package is meant to be a reusable library of code, to be used by other packages. bboard 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. -
+
The URL from which people will download your package when it is done. Just use the default for this, you can change it later. -
+
Just use the default here, which by convention is 0.1d. -
+
Just use the default here. -
+
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. -
Click the button "Create Package". -
At this point, APM will create a directory called +
+
Click the button "Create Package". +
At this point, APM will create a directory called ROOT/packages/notes. -
Since we didn't create any files for the package before, the +
Since we didn't create any files for the package before, the directory that APM created will be empty except for the notes.info file. At this point, create a file called ROOT/packages/notes/sql/notes-create.sql and put the add the data model that we created before to this file. You should also create a file called ROOT/packages/notes/sql/notes-drop.sql that drops the - data model.
-After you do this, go back to the main APM page. From there, click + data model.
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 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 - packge, they have not been loaded into the database. For 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 do the same thing for data model files. -
-Now go back to the main management page for the notes +
Now go back to the main management page for the notes If your package has parameters, create them using the "Manage - Parameter Information" link.
The new package has been created and installed in the server. At + Parameter Information" 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 these instructions. If so, then you just do this: -
-+% cd ROOT/packages % cvs add notes @@ -601,44 +388,34 @@ % 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 submission guidelines. -
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 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 - own. What we have to do is mount the application into the site + 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. This process is slightly more complex than in OpenACS 3.x, but also much more flexible. -
-+
In OpenACS 3.x, everything in the site was implicitly mounted underneath ROOT/www. AOLserver automatically took any URL like /foo/bar/moo/baz.html and mapped it to the file ROOT/www/foo/bar/moo/baz.html. This was conveniently simple, but lacked flexibility. In particular, it was difficult to map content that lived outside the page root into the site, and it was also hard to map mulitiple URLs to the same place in the file system. -
-+
In OpenACS 4.5, administrators can define an arbitrary mapping between the URLs the user types and the actual file in the file system 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 + 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 us to easily map package instances to URLs As we said before, each instance of an application has its own set of parameters settings and @@ -652,8 +429,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 @@ -662,17 +438,14 @@ 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. -
-+
After you get done doing this, try typing this URL into your browser: -
-+http://your-server.your-domain.com/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 @@ -682,68 +455,21 @@ later document, we'll see how to write your applicationn so that the code can detect from where in the site 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. -
+
Manages package upgrades. -
- Manages information on all package instances in a site. For +
+ 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. -