From a702b2877e9ef5dbc075a525dbc359e0e84db244 Mon Sep 17 00:00:00 2001
From: Timo Stollenwerk <timo@zmag.de>
Date: Mon, 21 Jun 2010 09:07:11 +0000
Subject: [PATCH] documentation for email notification added.

svn path=/plone.app.discussion/trunk/; revision=37368
---
 docs/source/email-notification.txt | 93 ++++++++++++++++++++++++++++++
 docs/source/index.txt              |  1 +
 2 files changed, 94 insertions(+)
 create mode 100644 docs/source/email-notification.txt

diff --git a/docs/source/email-notification.txt b/docs/source/email-notification.txt
new file mode 100644
index 0000000..4b88297
--- /dev/null
+++ b/docs/source/email-notification.txt
@@ -0,0 +1,93 @@
+==================
+Email Notification
+==================
+
+This document describes the plone.app.discussion email notification feature.
+
+
+Introduction
+============
+
+plone.app.discussion allows users and administrators to be notified about new 
+comments by email. There are two kinds of email notification:
+
+1) **User notification**: Tell users when a comment has been added.
+    
+   This method composes and sends emails to all users that have added a comment 
+   to this conversation and enabled user notification.
+       
+   This requires the user_notification setting to be enabled in the discussion 
+   control panel. 
+  
+  
+2) **Moderator notification**: Tell the moderator when a comment needs attention.
+    
+   This method sends an email to the site admin (mail control panel setting) if
+   comment moderation is enabled and a new comment has been added that needs to
+   be approved.   
+   
+   This requires the moderator_notification to be enabled in the discussion 
+   control panel and the comment_review_workflow enabled for the comment content
+   type.
+
+
+.. note:: The user notification feature requires z3c.form >= 2.3.3.
+
+
+User Notification
+=================
+
+*plone/app/discussion/comment.py*
+
+.. literalinclude:: ../../plone/app/discussion/comment.py
+   :language: python
+   :encoding: utf-8
+   :pyobject: notify_user
+
+
+Moderator Notification
+======================
+
+*plone/app/discussion/comment.py*
+
+.. literalinclude:: ../../plone/app/discussion/comment.py
+   :language: python
+   :encoding: utf-8
+   :pyobject: notify_moderator
+
+
+
+Event Subscribers
+=================
+
+Email notifications are triggered by event subscribers that are called when a 
+comment has been added to a page.
+
+.. note::
+  In Plone 3, the event subscribers were located in the zope.lifecycleevent 
+  package. They moved to zope.app.container in Plone 4. Therefore 
+  plone.app.discussion registers one of the two subscribers, dependent on the  
+  Plone version. 
+
+To create custom email notifications, register a new event subscriber or 
+override an existing one.
+
+
+Plone 3 Event Subscribers
+-------------------------
+
+*plone/app/discussion/subscribers.zcml*
+
+.. literalinclude:: ../../plone/app/discussion/subscribers.zcml
+   :encoding: utf-8
+   :lines: 40-52
+
+
+Plone 4 Event Subscribers
+-------------------------
+
+*plone/app/discussion/subscribers.zcml*
+
+.. literalinclude:: ../../plone/app/discussion/subscribers.zcml
+   :encoding: utf-8
+   :lines: 97-109
diff --git a/docs/source/index.txt b/docs/source/index.txt
index 01c3eba..a4a4c81 100644
--- a/docs/source/index.txt
+++ b/docs/source/index.txt
@@ -17,6 +17,7 @@ Contents:
    architecture.txt
    design.txt
    captcha.txt
+   email-notification.txt
    api.txt
    
 .. include:: ../../CHANGES.txt