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 + 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:
A computer with a working installation of OpenACS 4.6. If you don't have this, see Installation Overview.
Example files, which are included in the standard OpenACS 4.6.2 distribution. -
Figure 8.1. Assumptions in this section
| 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. +
Figure 8.1. Assumptions in this section
| 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 |
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)
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) + Notes
Package Plural: - Notes (Sample Applications)
+ Notes
Initial Version: 0.1d
Summary: This is my first package. -
At the bottom, click - . -
At the bottom, click + . +
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.
Browse to -http://yourserver:8000/admin/site-map/.
Click the new sub - folder link on the Main Site - line.
Type samplenote -and click .
Click the new -application link on the samplenote line.
Type Sample Note -where it says + 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.
Browse to +http://yourserver.test:8000/admin/site-map/.
Click the new sub + folder link on the top row in the + Site Map table.
Type note +and click .
This creates a new row called +note. In the new row, click the new +application link
Type Sample Note where +it says untitled, choose -Notes (Sample Application) from the -drop-down list, and click -. +Notes from the drop-down list, and +click .
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 + 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/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 + 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]$ 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 +[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.
Open the file index.xml + 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 @@ -81,14 +98,12 @@ 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 + 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 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) @@ -100,10 +115,11 @@ 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 + 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.
[service0@yourserver xml]$ cd .. + 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 ..