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.5 -r1.6
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml	11 Dec 2003 21:39:48 -0000	1.5
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml	26 Jan 2004 15:39:44 -0000	1.6
@@ -304,4 +304,137 @@
 </para>
       </sect2>
 
+  <sect2>
+    <title>Notifications</title>
+    <authorblurb>
+      <para>by <ulink url="mailto:dave@student.usyd.edu.au">David Bell</ulink> and <ulink url="mailto:simon@collaboraid.net">Simon Carstensen</ulink></para>
+    </authorblurb>
+
+    <para>The notifications package allows you to send notifications through any 
+    defined communications medium (e.g. email, sms) upon some event occuring within 
+    the system.</para>
+    <para>This tutorial steps through the process of integrating the notifications 
+    package with your package.</para>
+   
+    <para>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).</para>
+
+    <programlisting>
+    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();
+    </programlisting>
+
+    <para>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</para>
+
+    <programlisting>
+        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
+    </programlisting>
+
+    <para>This code is placed in the tcl procedure that creates blog entries, right after
+    the entry gets created in the code. The <computeroutput>$blog(package_id)</computeroutput> 
+    is the OpenACS object_id of the Weblogger instance to which the entry has been posted to 
+    and the <computeroutput>$new_content</computeroutput> is the content of the entry.</para>
+
+    <para>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.</para>
+
+    <para>Such a link can be created using the <computeroutput>notification::display::request_widget</computeroutput> 
+    proc:</para>
+    <programlisting>
+    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] \
+    ]
+    </programlisting>
+
+    <para>which will return something like
+
+    <programlisting>
+    You may &lt;a href="/notifications/request-new?..."&gt;request notification&lt;/a&gt; for Weblogger.</programlisting>
+
+    which can be readily put on the blog index page. The <computeroutput>pretty_name</computeroutput> 
+    parameter is what appears at the end of the text returned (i.e. "... request notification&lt;/a&gt; for pretty_name"), 
+    The <computeroutput>url</computeroutput> parameter should be set to the address we want the user 
+    to be redirected to after they have finished the subscription process.</para>
+
+    <para>This should be all you need to implement a notification system. For more examples
+    look at the forums package.</para>
+  </sect2>
+
 </sect1>