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 -N -r1.4.2.2 -r1.4.2.3
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml 15 Dec 2003 14:18:48 -0000 1.4.2.2
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml 16 Jan 2004 14:27:49 -0000 1.4.2.3
@@ -61,11 +61,11 @@
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/samplenote/
-[service0 samplenote]$ mkdir -p www/doc/xml
-[service0 samplenote]$ cd www/doc/xml
-[service0 xml]$ cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/samplenote/* .
-[service0 xml]$
+ [service0@yourserver service0]$ cd /var/lib/aolserver/service0/packages/samplenote/
+[service0@yourserver samplenote]$ mkdir -p www/doc/xml
+[service0@yourserver samplenote]$ cd www/doc/xml
+[service0@yourserver xml]$ cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/samplenote/* .
+[service0@yourserver 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
@@ -86,7 +86,7 @@
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
+ [service0@yourserver 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)
@@ -102,7 +102,7 @@
Writing admin-guide.html for chapter(admin-guide)
Writing bi01.html for bibliography
Writing index.html for book
-[service0 xml]$
+[service0@yourserver xml]$
Verify that the documentation was generated and reflects
your changes by browsing to http://yoursite:8000/samplenote/doc
@@ -114,20 +114,20 @@
traverse the directory tree manually and add as you go. (More on
CVS)
- [service0 xml]$ cd ..
-[service0 doc]$ cd ..
-[service0 www]$ cd ..
-[service0 samplenote]$ cd ..
-[service0 packages]$ cvs add samplenote/
+ [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 packages]$ cd samplenote/
-[service0 samplenote]$ cvs add www
+[service0@yourserver packages]$ cd samplenote/
+[service0@yourserver samplenote]$ cvs add www
Directory /cvsroot/service0/packages/samplenote/www added to the repository
-[service0 samplenote]$ cd www
-[service0 www]$ cvs add doc
+[service0@yourserver samplenote]$ cd www
+[service0@yourserver www]$ cvs add doc
Directory /cvsroot/service0/packages/samplenote/www/doc added to the repository
-[service0 www]$ cd doc
-[service0 doc]$ cvs add *
+[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
@@ -152,13 +152,13 @@
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 doc]$ cd xml
-[service0 xml]$ cvs add Makefile index.xml
+[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 xml]$ cd ../../..
-[service0 samplenote]$ cvs commit -m "new package"
+[service0@yourserver xml]$ cd ../../..
+[service0@yourserver samplenote]$ cvs commit -m "new package"
cvs commit: Examining .
cvs commit: Examining www
cvs commit: Examining www/doc
@@ -170,7 +170,7 @@
initial revision: 1.1
done
(many lines omitted)
-[service0 samplenote]$
+[service0@yourserver samplenote]$
Delete with confirmation
@@ -179,7 +179,7 @@
Add this column to the table_def in index.tcl
{delete "" {} {<td><a href="note-delete?note_id=$note_id">Delete</a></td>}}
Create the delete confirmation/execution page.
- [service0 www]$ emacs note-delete.tcl
+ [service0@yourserver www]$ emacs note-delete.tcl
ad_page_contract {
A page that gets confirmation and then delete notes.
@@ -224,7 +224,7 @@
script execution.
The database commands:
- [service0 www]$ emacs note-delete.xql
+ [service0@yourserver www]$ emacs note-delete.xql
<?xml version="1.0"?>
<queryset>
<fullquery name="do_delete">
@@ -239,7 +239,7 @@
</fullquery>
</queryset>
And the adp page:
- [service0 www]$ emacs note-delete.adp
+ [service0@yourserver www]$ emacs note-delete.adp
<master>
<property name="title">@title@</property>
<property name="context">{@title@}</property>
@@ -304,4 +304,137 @@
+
+ Notifications
+
+ by David Bell and Simon Carstensen
+
+
+ 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.
+
+