by Joel Aufrecht 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: How to use the APM to start a new package How to write documentation, including self-documenting code How to set up the database tables and procedures. How to write web pages. How to add automated regression testing to your packages How to debug your package You will need: A computer with a working installation of OpenACS 4.6. If you don't have this, see . Example files, which are included in the standard OpenACS &version; distribution.

Fully qualified domain name of your server yourserver.test URL of your server http://yourserver.test:8000 Name of development account service0 New Package key samplenote

Tee ACS Package Manager initializes new packages. This sets up the initial directories, meta-information files, and database entries for a new package. Browse to http://yourserver:8000/acs-admin/apm. Click Create a New Package. Fill in the fields listed below. Tab through the rest. (Some will change automatically. Don't mess with those.) Package Key: samplenote Package Name: Notes (Sample Application) Package Plural: Notes (Sample Applications) Initial Version: 0.1d Summary: This is my first package. At the bottom, click Create Package. 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. Browse to http://yourserver:8000/admin/site-map/. Click the new sub folder link on the Main Site line. Type samplenote and click New. Click the new application link on the samplenote line. Type Sample Note where it says untitled, choose Notes (Sample Application) from the drop-down list, and click New. By mounting the package, we've caused all requests to http://yourserver.test/samplenote to be satisfied from the files at /web/service0/packages/samplenote/www. It's time to document. For a new package you should 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/package-documentation.xml. You then open that file with emacs, write the requirements and design section, generate html, and start coding. For this tutorial, you should instead install the pre-written documentation files for the tutorial app, examine them, generate html, read it, and then proceed to build the package. Store any diagrams in native format in the www/doc/xml directory, and store png or jpg versions of the diagrams in the www/doc direcory. Pre-written documentation is available for this tutorial, so we'll copy that documentation and edit it. 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]$ cp /web/service0/packages/acs-core-docs/www/files/samplenote/* www/doc/xml/ [service0@anthrax samplenote]$ mv www/doc/xml/*.dia www/doc/ [service0@anthrax samplenote]$ mv www/doc/xml/*.png www/doc/ [service0@anthrax samplenote]$ 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. 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 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 samplenote]$ cd www/doc/xml [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 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 in the xml 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. [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]$