# HG changeset patch
# User Sylvain Thénault <sylvain.thenault@logilab.fr>
# Date 1366899056 -7200
# Node ID f5b40b66d36ea039b5dc668a80f729cb446848f9
# Parent  57f8a02550cc4ec54ff79777128ba6fc35682b2f
[notification] introduce an official `notify_on_commit` function

It provides a proper notification api instead of replacing it by yet another
clumsy one.


Closes #2837251

diff -r 57f8a02550cc -r f5b40b66d36e doc/book/en/devrepo/repo/notifications.rst
--- a/doc/book/en/devrepo/repo/notifications.rst	Thu Apr 25 15:45:38 2013 +0200
+++ b/doc/book/en/devrepo/repo/notifications.rst	Thu Apr 25 16:10:56 2013 +0200
@@ -3,4 +3,27 @@
 Notifications management
 ========================
 
-.. XXX FILLME
+CubicWeb provides a machinery to ease notifications handling. To use it for a
+notification:
+
+* write a view inheriting from
+  :class:`~cubicweb.sobjects.notification.NotificationView`.  The usual view api
+  is used to generated the email (plain text) content, and additional
+  :meth:`~cubicweb.sobjects.notification.NotificationView.subject` and
+  :meth:`~cubicweb.sobjects.notification.NotificationView.recipients` methods
+  are used to build the email's subject and
+  recipients. :class:`NotificationView` provides default implementation for both
+  methods.
+
+* write a hook for event that should trigger this notification, select the view
+  (without rendering it), and give it to
+  :func:`cubicweb.hooks.notification.notify_on_commit` so that the notification
+  will be sent if the transaction succeed.
+
+
+.. XXX explain recipient finder and provide example
+
+API details
+~~~~~~~~~~~
+.. autoclass:: cubicweb.sobjects.notification.NotificationView
+.. autofunction:: cubicweb.hooks.notification.notify_on_commit
diff -r 57f8a02550cc -r f5b40b66d36e hooks/notification.py
--- a/hooks/notification.py	Thu Apr 25 15:45:38 2013 +0200
+++ b/hooks/notification.py	Thu Apr 25 16:10:56 2013 +0200
@@ -1,4 +1,4 @@
-# copyright 2003-2012 LOGILAB S.A. (Paris, FRANCE), all rights reserved.
+# copyright 2003-2013 LOGILAB S.A. (Paris, FRANCE), all rights reserved.
 # contact http://www.logilab.fr/ -- mailto:contact@logilab.fr
 #
 # This file is part of CubicWeb.
@@ -28,16 +28,26 @@
 from cubicweb.sobjects.supervising import SupervisionMailOp
 
 
-@deprecated('[3.17] use ActualNotificationOp instead (using the 3.10 data API)')
+@deprecated('[3.17] use notify_on_commit instead')
 def RenderAndSendNotificationView(session, view, viewargs=None):
+    notify_on_commit(session, view, viewargs)
+
+
+def notify_on_commit(session, view, viewargs=None):
+    """register a notification view (see
+    :class:`~cubicweb.sobjects.notification.NotificationView`) to be sent at
+    post-commit time, ie only if the transaction has succeeded.
+
+    `viewargs` is an optional dictionary containing extra argument to be given
+    to :meth:`~cubicweb.sobjects.notification.NotificationView.render_and_send`
+    """
     if viewargs is None:
         viewargs = {}
-    notif_op = ActualNotificationOp.get_instance(session)
+    notif_op = __RenderAndSendNotificationOp.get_instance(session)
     notif_op.add_data((view, viewargs))
-    return ActualNotificationOp
 
 
-class ActualNotificationOp(hook.DataOperationMixIn, hook.Operation):
+class _RenderAndSendNotificationOp(hook.DataOperationMixIn, hook.Operation):
     """End of the notification chain. Do render and send views after commit
 
     All others Operations end up adding data to this Operation.
@@ -101,7 +111,7 @@
         # #103822)
         if comment and entity.comment_format != 'text/rest':
             comment = normalize_text(comment, 80)
-        notif_op = ActualNotificationOp.get_instance(self._cw)
+        notif_op = _RenderAndSendNotificationOp.get_instance(self._cw)
         viewargs = {'comment': comment,
                     'previous_state': entity.previous_state.name,
                     'current_state': entity.new_state.name}
@@ -121,7 +131,7 @@
                                 rset=rset, row=0)
         if view is None:
             return
-        notif_op = ActualNotificationOp.get_instance(self._cw)
+        notif_op = _RenderAndSendNotificationOp.get_instance(self._cw)
         notif_op.add_data((view, {}))
 
 
@@ -137,7 +147,7 @@
         view = self.select_view('notif_%s' % self.event, rset=rset, row=0)
         if view is None:
             return
-        notif_op = ActualNotificationOp.get_instance(self._cw)
+        notif_op = _RenderAndSendNotificationOp.get_instance(self._cw)
         notif_op.add_data((view, {}))
 
 
@@ -151,7 +161,7 @@
             view = session.vreg['views'].select('notif_entity_updated', session,
                                                 rset=session.eid_rset(eid),
                                                 row=0)
-            notif_op = ActualNotificationOp.get_instance(self._cw)
+            notif_op = _RenderAndSendNotificationOp.get_instance(self._cw)
             notif_op.add_data((view, {}))