Changes between Initial Version and Version 1 of TracDev/Proposals/AdvancedNotification/INotificationFormatter

Timestamp:

Nov 17, 2012, 11:31:25 PM (11 years ago)

Author:

Peter Suter

Comment:

Document the proposed INotificationFormatter extension point.

TracDev/Proposals/AdvancedNotification/INotificationFormatter

@@ +1 @@
+== Extension Point : ''INotificationFormatter'' ==
+
+||'''Interface'''||''INotificationFormatter''||'''Since'''||[wiki:TracDev/ApiChanges/1.1.1#INotificationFormatter 1.1.1]||
+||'''Module'''||''trac.notification''||'''Source'''||[source:trunk/trac/notification/api.py#/INotificationFormatter api.py]||
+
+The ''INotificationFormatter'' formats [TracNotification notification] events to messages in various formats ready to be distributed.
+
+== Purpose ==
+
+Trac provides an extendible and flexible notification system, that historically has sent plain text emails for ticket changes. Notifications of different event realms (e.g. wiki notifications), transports (e.g. SMS) and message formats (e.g. HTML messages) might all require different formatting logic though.
+
+== Usage ==
+
+Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
+
+A simple `styles()` method lists the supported MIME types for a given transport and event realm.
+
+The `format()` method formats a notification event. It receives the following parameters:
+* `transport`: The name of the transports that should be used. (See [wiki:INotificationDistributor INotificationDistributor])
+* `style`: The style that should be used. One of those returned by `styles()`.
+* `event`: A `trac.notification.api.NotificationEvent` instance describing the event about which the recipients should be notified.
+
+It should return the formatted message. The exact return type depends on the transport.
+
+== Examples ==
+
+The following example formats notifications by SMS. (The `sms` library does not exist. Several commercial SMS services provide real APIs.)
+
+{{{#!python
+from trac.core import *
+from trac.notification.api import INotificationFormatter
+
+class ShortTicketNotificationFormatter(Component):
+
+    implements(INotificationFormatter)
+
+    # INotificationFormatter methods
+    
+    def styles(self, transport, realm):
+        if transport == 'sms' and realm == 'ticket':
+            yield 'text/plain and short'
+
+    def format(self, transport, style, event):
+        if transport == 'sms' and event.realm == 'ticket':
+            return "#{0} {1} by {2}" % (event.target,
+                                        event.category,
+                                        event.author)
+}}}
+
+== Available Implementations ==
+
+Only `trac.ticket.notification.TicketFormatter` is part of core Trac.
+
+Various other formatters will be part of th:AnnouncerPlugin.
+
+== Additional Information and References ==
+
+ * [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.notification.api.INotificationFormatter-class.html epydoc]
+ * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_notification.html#trac.notification.api.INotificationFormatter API Reference]
+ * Related to the [wiki:INotificationDistributor INotificationDistributor]
+ * This interface originated in th:AnnouncerPlugin as `IAnnouncementFormatter`.
+   * DONE Dropped the `alternative_style_for()` method. (The distributor can select fallbacks without this.)
+   * DONE Dropped the `realm` parameter to the `format()` method. (Use `event.realm` instead.)