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 /var/lib/aolserver/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-documentation-template.xml to myfirstpackage/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 service0]$ cd /var/lib/aolserver/service0/packages/myfirstpackage/
[service0 myfirstpackage]$ mkdir -p www/doc/xml
[service0 myfirstpackage]$ cd www/doc/xml
[service0 xml]$ cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/myfirstpackage/* .
[service0 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 OpenACS Documentation Guide

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 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 xml]$

Verify that the documentation was generated and reflects your changes by browsing to http://yoursite:8000/myfirstpackage/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 xml]$ cd ..
[service0 doc]$ cd ..
[service0 www]$ cd ..
[service0 myfirstpackage]$ cd ..
[service0 packages]$ cvs add myfirstpackage/
Directory /cvsroot/service0/packages/myfirstpackage added to the repository
[service0 packages]$ cd myfirstpackage/
[service0 myfirstpackage]$ cvs add www
Directory /cvsroot/service0/packages/myfirstpackage/www added to the repository
[service0 myfirstpackage]$ cd www
[service0 www]$ cvs add doc
Directory /cvsroot/service0/packages/myfirstpackage/www/doc added to the repository
[service0 www]$ cd doc
[service0 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/myfirstpackage/www/doc/xml added to the repository
cvs add: use 'cvs commit' to add these files permanently
[service0 doc]$ cd xml
[service0 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 xml]$ cd ../../..
[service0 myfirstpackage]$ 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/myfirstpackage/www/doc/admin-guide.html,v
done
Checking in www/doc/admin-guide.html;
/cvsroot/service0/packages/myfirstpackage/www/doc/admin-guide.html,v  <--  admin-guide.html
initial revision: 1.1
done
(many lines omitted)
[service0 myfirstpackage]$

You can track comments for any ACS Object. Here we'll track comments for notes. On the note-edit.tcl/adp pair, which is used to display individual notes, we want to put a link to add comments at the bottom of the screen. If there are any comments, we want to show them.

First, we need to generate a url for adding comments. In note-edit.tcl:

 set comment_add_url "[general_comments_package_url]comment-add?[export_vars {
  { object_id $note_id } 
  { object_name $title } 
  { return_url "[ad_conn url]?[ad_conn query]"} 
 }]"
 

This calls a global, public tcl function that the general_comments package registered, to get its url. You then embed in that url the id of the note and its title, and set the return_url to the current url so that the user can return after adding a comment.

We need to create html that shows any existing comments. We do this with another general_comments function:

set comments_html [general_comments_get_comments
     -print_content_p 1 $note_id]

First, we pass in an optional parameter that that says to actually show the contents of the comments, instead of just the fact that there are comments. Then you pass the note id, which is also the acs_object id.

We put our two new variables in the note-edit.adp page.

<a href="@comment_add_url@">Add a comment</a>
 @comments_html@

There are at least two flavors of admin user interface:

You can associate any ACS Object with one or more categories. In this tutorial we'll show how to equip your application with user interface to take advantage of the Categories service.

We'll start by installing the Categories service. Go to /acs/admin and install it. This step won't be necessary for the users of your applications because you'll create a dependency with the Package Manager which will take care that the Categories service always gets installed when your application gets installed.

Now that we have installed the Categories service we can proceed to modifying our application so that it can take advantage of it. We'll do it in three steps:

There are several facilities for profiling your code in OpenACS. The first thing to do is to install the developer-support package and play around with it. But there is also support in the API for profiling your code: profiling your code using ds_profile

Browse to the package manager. Click on tutorialapp.

Click on Generate a distribution file for this package from the filesystem.

Click on the file size (37.1KB) after the label Distribution File: and save the file to /tmp.

The notifications package allows you to send notifications through any defined communications medium (e.g. email, sms) upon some event occuring within the system.

This tutorial steps through the process of integrating the notifications package with your package.

First step is to create the notification types. To do this a script similar to the one below needs to be loaded into Postgresql. I create this script in a package-name/sql/postgresql/package-name-notifications-init.sql file. I then load this file from my create sql file. The following code snippet is taken from Weblogger. It creates a lars_blogger_notif notification type (which was created above).

    create function inline_0() returns integer as '
    declare
            impl_id integer;
            v_foo   integer;
    begin
        -- the notification type impl
        impl_id := acs_sc_impl__new (
                      ''NotificationType'',
                      ''lars_blogger_notif_type'',
                      ''lars-blogger''
        );

        v_foo := acs_sc_impl_alias__new (
                    ''NotificationType'',
                    ''lars_blogger_notif_type'',
                    ''GetURL'',
                    ''lars_blogger::notification::get_url'',
                    ''TCL''
        );

        v_foo := acs_sc_impl_alias__new (
                    ''NotificationType'',
                    ''lars_blogger_notif_type'',
                    ''ProcessReply'',
                    ''lars_blogger::notification::process_reply'',
                    ''TCL''
        );

        PERFORM acs_sc_binding__new (
                    ''NotificationType'',
                    ''lars_blogger_notif_type''
        );

        v_foo:= notification_type__new (
	        NULL,
                impl_id,
                ''lars_blogger_notif'',
                ''Blog Notification'',
                ''Notifications for Blog'',
		now(),
                NULL,
                NULL,
		NULL
        );

        -- enable the various intervals and delivery methods
        insert into notification_types_intervals
        (type_id, interval_id)
        select v_foo, interval_id
        from notification_intervals where name in (''instant'',''hourly'',''daily'');

        insert into notification_types_del_methods
        (type_id, delivery_method_id)
        select v_foo, delivery_method_id
        from notification_delivery_methods where short_name in (''email'');

        return (0);
    end;
    ' language 'plpgsql';

    select inline_0();
    drop function inline_0();
    

The next step is to setup our notification creation. A new notification must be added to the notification table for each blog entry added. We do this using the notification::new procedure

        notification::new \
            -type_id [notification::type::get_type_id \
            -short_name lars_blogger_notif] \
            -object_id $blog(package_id) \
            -response_id $blog(entry_id) \
            -notif_subject $blog(title) \
            -notif_text $new_content
    

This code is placed in the tcl procedure that creates blog entries, right after the entry gets created in the code. The $blog(package_id) is the OpenACS object_id of the Weblogger instance to which the entry has been posted to and the $new_content is the content of the entry.

The final step is to setup the notification subscription process. In this example we want to let a user find out when a new entry has been posted to the blog. To do this we put a link on the blog that allows them to subscribe to notifications of new entries. The notifications/requests-new page is very handy in this situation.

Such a link can be created using the notification::display::request_widget proc:

    set notification_chunk [notification::display::request_widget \
        -type lars_blogger_notif \
        -object_id $package_id \
        -pretty_name [lars_blog_name] \
        -url [lars_blog_public_package_url] \
    ]
    

which will return something like

    You may <a href="/notifications/request-new?...">request notification</a> for Weblogger.

which can be readily put on the blog index page. The pretty_name parameter is what appears at the end of the text returned (i.e. "... request notification</a> for pretty_name"), The url parameter should be set to the address we want the user to be redirected to after they have finished the subscription process.

This should be all you need to implement a notification system. For more examples look at the forums package.

One of the nice things about using the OpenACS object system is that it has a built-in facility for tracking hierarchical data in an efficient way. The algorithm behind this is called tree_sortkey.. This is built into the PostgreSql portion of the acs_objects table. (If you are using Oracle, then you should just use CONNECT BY to build your hierarchical queries, using context_id as the parent_id column). Note that packages based on acs_objects use and/or abuse context_id inconsistently to maintain a hierarchy.

Any time your tables are subclasses of the acs_objects table, then you automatically get the ability to structure them hierarchically. The way you do this is currently via the context_id column of acs_objects (Note that there is talk of adding in a parent_id column instead, because the use of context_id has been ambiguous in the past). So when you want to build your hierarchy, simply set the context_id values. Then, when you want to make hierarchical queries, you can do them as follows:

      db_multirow categories blog_categories "
      SELECT
      c.*,
      o.context_id,
      tree_level(o.tree_sortkey)
      FROM
      blog_categories c,
      acs_objects o
      WHERE
      c.category_id = o.object_id
      ORDER BY
      o.tree_sortkey"
    

Note the use of the tree_level() function, which gives you the level, starting from 1, 2, 3...

Here's an example, pulling all of the children for a given parent:

      SELECT 
      children.*,
      tree_level(children.tree_sortkey) -
        tree_level(parent.tree_sortkey) as level
      FROM 
      some_table parent, 
      some_table children
      WHERE 
      children.tree_sorktey between parent.tree_sortkey and tree_right(parent.tree_sortkey)
      and parent.tree_sortkey <> children.tree_sortkey
      and parent.key = :the_parent_key;
      

The reason we substract the parent's tree_level from the child's tree_level is that the tree_levels are global, so if you want the parent's tree_level to start with 0, you'll want the subtraction in there. This is a reason you'll commonly see magic numbers in tree_sortkey SQL queries, like tree_level(children.tree_sortkey) - 4. That is basically an incorrect way to do it, and subtracting the parent's tree_level is the preferred method.

This example does not include the parent. To return the entire subtree including the parent, leave out the non-equals clause:

      SELECT
      subtree.*,
      tree_level(children.tree_sortkey) -
        tree_level(parent.tree_sortkey) as level
      FROM some_table parent, some_table subtree
      WHERE 
      subtree.tree_sorktey between parent.tree_sortkey and tree_right(parent.tree_sortkey)
      and parent.key = :the_parent_key;
    

If you are using the Content Repository, you get a similar facility, but the parent_id column is already there. Note you can do joins with tree_sortkey:

      SELECT
      p.item_id,
      repeat(:indent_pattern, (tree_level(p.tree_sortkey) - 5)* :indent_factor) as indent,
      p.parent_id as folder_id,
      p.project_name
      FROM pm_projectsx p, cr_items i
      WHERE p.project_id = i.live_revision
      ORDER BY i.tree_sortkey
    

This rather long thread explains How tree_sortkeys work and this paper describes the technique for tree_sortkeys, although the OpenACS implementation has a few differences in the implementation, to make it work for many languages and the LIKE construct in Postgres.