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 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.

You will need:

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

This creates a package rooted at /web/service0/packages/samplenote. This is the "home directory" of our new package, and all files in the package will be within this directory.

In order to see your work in progress, you must create a map between the URL space of incoming requests and the package. You do this by mounting the package in the Site Map. This creates a link between the incoming URL and an instance of the package. (More on Site Maps and nodes)

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

By mounting the package, we've caused all requests to http://yourserver.test:8000/note to be satisfied from the files at /web/service0/packages/samplenote/www.

It's time to document. For the tutorial we'll use pre-written documentation. When creating a package from scratch, start by copying the documentation template from /web/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-documentation-template.xml to yourpackage/www/docs/xml/index.xml.

You then edit that file with emacs to write the requirements and design sections, generate the html, and start coding. Store any supporting files, like page maps or schema diagrams, in the www/doc/xml directory, and store png or jpg versions of supporting files in the www/doc directory.

For this tutorial, you should instead install the pre-written documentation files for the tutorial app. Log in as service0, create the standard directories, and copy the prepared documentation:

[service0@anthrax service0]$ cd /web/service0/packages/samplenote/
[service0@anthrax samplenote]$ mkdir -p www/doc/xml
[service0@anthrax samplenote]$ cd www/doc/xml
[service0@anthrax xml]$ cp /web/service0/packages/acs-core-docs/www/files/samplenote/* .
[service0@anthrax xml]$

OpenACS uses DocBook for documentation. DocBook is an XML standard for semantic markup of documentation. That means that the tags you use indicate meaning, not intended appearance. The style sheet will determine appearance. You will edit the text in an xml file, and then process the file into html for reading.

Open the file index.xml in emacs. Examine the file. Find the version history (look for the tag <revhistory>). Add a new record to the document version history. Look for the <authorgroup> tag and add yourself as a second author. Save and exit. For tips on editing SGML files in emacs, see the section called “DocBook and Documentation”

Process the xml file to create html documentation. The html documentation, including supporting files such as pictures, is stored in the www/docs/ directory. A Makefile is provided to generate html from the xml, and copy all of the supporting files. If Docbook is set up correctly, all you need to do is:

[service0@anthrax xml]$ make
cd .. ; /usr/bin/xsltproc ../../../acs-core-docs/www/xml/openacs.xsl xml/index.xml
Writing requirements-introduction.html for sect1(requirements-introduction)
Writing requirements-overview.html for sect1(requirements-overview)
Writing requirements-cases.html for sect1(requirements-cases)
Writing sample-data.html for sect1(sample-data)
Writing requirements.html for chapter(requirements)
Writing design-data-model.html for sect1(design-data-model)
Writing design-ui.html for sect1(design-ui)
Writing design-config.html for sect1(design-config)
Writing design-future.html for sect1(design-future)
Writing filename.html for chapter(filename)
Writing user-guide.html for chapter(user-guide)
Writing admin-guide.html for chapter(admin-guide)
Writing bi01.html for bibliography
Writing index.html for book
[service0@yourserver xml]$

Verify that the documentation was generated and reflects your changes by browsing to http://yoursite:8000/samplenote/doc

Before you do any more work, make sure that your work is protected by putting it all into cvs. The cvs add command is not recursive, so you'll have to traverse the directory tree manually and add as you go. (More on CVS)

[service0@yourserver xml]$ cd ..
[service0@yourserver doc]$ cd ..
[service0@yourserver www]$ cd ..
[service0@yourserver samplenote]$ cd ..
[service0@yourserver packages]$ cvs add samplenote/
Directory /cvsroot/service0/packages/samplenote added to the repository
[service0@yourserver packages]$ cd samplenote/
[service0@yourserver samplenote]$ cvs add www
Directory /cvsroot/service0/packages/samplenote/www added to the repository
[service0@yourserver samplenote]$ cd www
[service0@yourserver www]$ cvs add doc
Directory /cvsroot/service0/packages/samplenote/www/doc added to the repository
[service0@yourserver www]$ cd doc
[service0@yourserver doc]$ cvs add *
cvs add: cannot add special file `CVS'; skipping
cvs add: scheduling file `admin-guide.html' for addition
cvs add: scheduling file `bi01.html' for addition
cvs add: scheduling file `data-model.dia' for addition
cvs add: scheduling file `data-model.png' for addition
cvs add: scheduling file `design-config.html' for addition
cvs add: scheduling file `design-data-model.html' for addition
cvs add: scheduling file `design-future.html' for addition
cvs add: scheduling file `design-ui.html' for addition
cvs add: scheduling file `filename.html' for addition
cvs add: scheduling file `index.html' for addition
cvs add: scheduling file `page-map.dia' for addition
cvs add: scheduling file `page-map.png' for addition
cvs add: scheduling file `requirements-cases.html' for addition
cvs add: scheduling file `requirements-introduction.html' for addition
cvs add: scheduling file `requirements-overview.html' for addition
cvs add: scheduling file `requirements.html' for addition
cvs add: scheduling file `sample-data.html' for addition
cvs add: scheduling file `sample.png' for addition
cvs add: scheduling file `user-guide.html' for addition
cvs add: scheduling file `user-interface.dia' for addition
cvs add: scheduling file `user-interface.png' for addition
Directory /cvsroot/service0/packages/samplenote/www/doc/xml added to the repository
cvs add: use 'cvs commit' to add these files permanently
[service0@yourserver doc]$ cd xml
[service0@yourserver xml]$ cvs add Makefile index.xml
cvs add: scheduling file `Makefile' for addition
cvs add: scheduling file `index.xml' for addition
cvs add: use 'cvs commit' to add these files permanently
[service0@yourserver xml]$ cd ../../..
[service0@yourserver samplenote]$ cvs commit -m "new package"
cvs commit: Examining .
cvs commit: Examining www
cvs commit: Examining www/doc
cvs commit: Examining www/doc/xml
RCS file: /cvsroot/service0/packages/samplenote/www/doc/admin-guide.html,v
done
Checking in www/doc/admin-guide.html;
/cvsroot/service0/packages/samplenote/www/doc/admin-guide.html,v  <--  admin-guide.html
initial revision: 1.1
done
(many lines omitted)
[service0@yourserver samplenote]$