Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/packages.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/packages.xml,v diff -u -r1.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/packages.xml 11 Dec 2003 21:39:48 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/packages.xml 24 Jun 2004 09:01:53 -0000 1.8 @@ -10,243 +10,91 @@ By Pete Su and Bryan Quinn - + Overview 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. + OpenACS. OpenACS packages are installed and maintained with the + OpenACS Package Manager (APM) which is part of the acs-admin + package. 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. - - Why package your software? + + Server file layout - 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: + Here is how an OpenACS &majorversion; server is laid out + starting from the Server root (ROOT): - - - +
+ Server file layout diagram + ROOT/ - bin/ - parameters/ - ad.ini - tcl/ - core tcl libraries here - www/ - admin/ - forums/ - site wide admin for forums - intranet/ - site wide admin for intranet - - ... and so on for all modules ... - - forums/ - pages for forums - admin/ - other admin pages for forums - intranet/ - pages for intranet - admin/ - other admin pages for intranet - doc/ - documentation - sql/ - core and application data models here - - ... 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/. - - - - - 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 &version; server is laid out: - - - - - -ROOT/ bin/ + Various executables and scripts for server maintanence. + content-repository-content-files/ + content repository content stored in the filesystem. + etc/ + Installation scripts and configuration files. packages/ acs-admin/ acs-api-browser/ - acs-content-repository/ - acs-core-docs/ - acs-developer-support/ - acs-kernel/ - acs-ldap-authentication/ - acs-messaging/ - acs-subsite/ - acs-templating/ - acs-test-harness/ - acs-util/ - acs-workflow/ - forums/ - forums.info - catalog/ - i18n message catalogs - lib/ - includable page fragments (.tcl/.adp pairs) - sql/ - oracle/ - oracle data model - postgresql/ - postgresql data model - tcl/ - tcl library code - www/ - user visible pages - admin/ - administration pages - doc/ - documentation - message-catalog/ - news/ - notification/ - page/ + ... many many more... + workflow/ + log/ + Server error and access logs tcl/ - bootstrap code + bootstrap code www/ - misc pages - + Pages not in packages (static content, customized pages) +
+ + + What a Package Looks Like + - Note that a major reorganization has happened here. The diagram only - expands the structure of the forums/ 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: + 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 means developers can track down + 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 independently from the OpenACS Core. - - - This structure makes it easy for developers to track - down 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 independently 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're at it, this tool should also automate package installation, dependency checking, upgrades, and package - removal. In OpenACS &version;, this tool is called the APM. + removal. In OpenACS &majorversion;, this tool is called the APM. - - - - - The 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. - - - - 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 - 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 &version; 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 - one or more arbitrary URLs in a running site. - - - - We will also discuss how to organize your files and queries so - they work with the OpenACS Query Dispatcher. - - - - - - What a Package Looks Like - - - OpenACS Package 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: + package for the "notes" application should look like. - - - +
+ Package file layout diagram + ROOT/ +-- packages/ APM Root | +-- notes/ Package Root | | - | | + | +-- notes.info Package Specification File | +-- sql/ | | | | | +-- oracle/ @@ -272,6 +120,10 @@ | | +-- notes-init.tcl Tcl Initialization | | +-- notes-init.xql Queries for notes-init.tcl (work in all DBs) | | +-- *.tcl Tcl Library Files + | +-- lib/ + | | | + | | +-- *.tcl Includable page logic + | | +-- *.adp Includable page templates | +-- www/ | | | | | +-- admin/ Administration UI @@ -282,28 +134,41 @@ | | | +-- ... Administration UI Pages | | | | | +-- doc/ Documentation - | | | +-- index.tcl Documentation Index Page + | | | +-- index.html Documentation Index Page | | | +-- ... Administration Pages + | | +-- resources/ Static Content + | | | +-- ... Static Content files | | +-- index.tcl UI Index Page | | +-- index.adp UI Index Template | | +-- index.xql Queries for UI Index page | | +-- *.tcl UI Logic Scripts | | +-- *.adp UI Templates | | +-- *-oracle.xql Oracle-specific Queries | | +-- *-postgresql.xql PostgreSQL-specific Queries - | +-- notes.info Package Specification File - +-- Other package directories. - - - + +-- 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. + + A special note on the + PACKAGE-KEY/www/resources + directory. + Files in this directory are available at + http://yourserver/resources/PACKAGE-KEY/... + and are returned without any permissions checking or even checks + that the package is installed or mounted. Files are returned + directly, so .tcl or .adp files are not sourced in these + directories. This makes it suitable for storing icons, css + files, javascript, and other static content which can be treated + this way. + - + + Package files @@ -314,6 +179,14 @@ + Package Specification File + The package specification file is an XML file generated and + maintained by the OpenACS Package Manager (APM). It specifies + information about the package including its parameters and its + files. + notes.info + + Data Model Creation Script Contains the SQL that creates the necessary data model and @@ -465,58 +338,97 @@ displays all of the tests available and provides information on how to run them. This file can have any extension, as long as its name is index. - /www/admin/tests/index.html + www/admin/tests/index.html Documentation Every package must include a full set of documentation that includes requirements and design documents, and user-level and developer-level documentation where appropriate. - /www/doc/ + www/doc/ Documentation Index Page The documentation directory must include a static HTML file with the name of index.html. - /www/doc/index.html + www/doc/index.html UI Logic Scripts Packages provide a UI for users to access the system. The UI is split into Logic and Templates. The logic scripts perform database queries and prepare variables for presentation by the associated templates. - /www/*.tcl + www/*.tcl UI Templates Templates are used to control the presentation of the UI. Templates receive a set of data sources from the logic scripts and prepare them for display to the browser. - /www/*.adp + www/*.adp UI Index Page The UI must have an index page composed of a logic script called index.tcl and a template called index.adp. - /www/index.tcl + www/index.tcl - - Package Specification File - The package specification file is an XML file generated and - maintained by the OpenACS Package Manager (APM). It specifies - information about the package including its parameters and its - files. - notes.info - - + +
+ + + The 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. + + + + 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 + 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 site + management features in OpenACS &majorversion; 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 + one or more arbitrary URLs in a running site. + + + + We will also discuss how to organize your files and queries so + they work with the OpenACS Query Dispatcher. + + + Making a Package @@ -681,8 +593,9 @@ Now go back to the main management page for the notes - If your package has parameters, create them using the "Manage - Parameter Information" link. + If your package has parameters, create them using the "Manage + Parameter Information" link. Define package callbacks via the "Tcl Callbacks (install, + instantiate, mount)" 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. @@ -692,9 +605,7 @@ - - -% cd ROOT/packages + % cd ROOT/packages % cvs add notes % cd notes % cvs add notes.info @@ -703,9 +614,10 @@ % cvs add *.sql % cd ROOT/packages/notes % cvs commit -m "add new package for notes" - + + @@ -733,22 +645,11 @@ pages underneath ROOT/www they will not appear on their 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. + will serve its pages. - 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 &version;, administrators can define an arbitrary mapping between the + In OpenACS &majorversion;, 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 @@ -779,17 +680,9 @@ - Then type this URL into your browser: - + Then type this URL into your browser: http://yourserver/notes/hello.html - - -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 Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml,v diff -u -r1.28 -r1.29 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml 24 Jun 2004 00:52:04 -0000 1.28 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml 24 Jun 2004 09:01:53 -0000 1.29 @@ -881,7 +881,7 @@ set subject "my subject" - set message "Bold not bold" + set message "<b>Bold</b> not bold" set from_addr "me@myemail.com" @@ -910,6 +910,7 @@ -body $message \ -extraheaders $extra_headers + Future Topics