Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml,v diff -u -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml 28 Feb 2003 05:26:59 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml 30 Mar 2003 20:31:48 -0000 1.2 @@ -1,63 +1,276 @@ - - OpenACS &version; Package Tutorial + + Creating a Package + + + by Joel Aufrecht + + + + Overview + 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 + - - by Joel Aufrecht - - - - Overview - How to create a package. Includes + + + Before you begin + You will need: - - Using the APM - - - Package create scripts, including using acs_objects and - standard __new, __delete, and __name stored procedures. - - - Integrating with the content management system - - - Integrating with OpenFTS/Oracle full text search - - - Integrating with notifications - - - Creating .tcl/adp pairs, including ad_page_contract and the - template system - - - Integrating with general_comments - - - Ad_form (draw from http://jongriffin.com/static/openacs/ad_form/using-ad-form) - - - Automated testing - - - caching - - - writing procs, ad_proc, tcl namespaces - - - putting all sql code in .xql, including using partialquery - - - using the html/text entry widget - + 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. + +
+ 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 + + + + +
- + + Use the APM to start a new package + 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. + + + + + + Mount the package in the site map + 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. + + + Write the Requirements and Design Specs + 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 + + + Add the new package to CVS + 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]$ + +