Changes between Initial Version and Version 1 of TracDev/PluginDevelopment/ExtensionPoints/trac.notification.api.IEmailDecorator

Timestamp:

Dec 6, 2014, 1:03:02 PM (9 years ago)

Author:

Peter Suter

Comment:

—

TracDev/PluginDevelopment/ExtensionPoints/trac.notification.api.IEmailDecorator

@@ +1 @@
+== Extension Point : ''IEmailDecorator'' ==
+
+||'''Interface'''||''IEmailDecorator''||'''Since'''||[wiki:TracDev/ApiChanges/1.1.3#IEmailDecorator 1.1.3]||
+||'''Module'''||''trac.notification''||'''Source'''||[source:trunk/trac/notification/api.py#/IEmailDecorator api.py]||
+
+An ''IEmailDecorator'' decorates [TracNotification notification] email, usually by adding additional email headers.
+
+== Purpose ==
+
+Trac provides an extendible and flexible notification system, that historically has sent emails formatted by some fixed logic.
+
+Now plugins can implement different [wiki:trac.notification.api.INotificationDistributor transports] and [wiki:trac.notification.api.INotificationFormatter formatters], decoupling the formatting logic from the transport implementation. IEmailDecorator allows also decoupling e.g. email title formatting and other header manipulation both from transport-neutral formatting logic and the email transport implementation.
+
+== Usage ==
+
+Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
+
+The `decorate_message()` decorates the email message as appropriate. The parameters are:
+* `event`: A `trac.notification.api.NotificationEvent` instance describing the event about which the recipients should be notified.
+* `message`: An `email.message.Message` to decorate.
+* `charset`: A `email.charset.Charset` to use for headers.
+
+== Examples ==
+
+The following example adds a custom `X-Trac-Notification-Author` header to emails:
+
+{{{#!python
+from trac.core import *
+from trac.notification.api import IEmailDecorator
+from trac.notification.mail import set_header
+
+class AuthorEmailDecorator(Component):
+
+    implements(IEmailDecorator)
+
+    # IEmailDecorator methods
+    
+    def decorate_message(self, event, message, charset):
+        set_header(message, 'X-Trac-Notification-Author', event.author, charset)
+}}}
+
+=== !ReplyToTicketDecorator
+
+Another example (adapted from [th:comment:4:ticket:10044 a feature request]) changes the reply-to address depending on the ticket id (so recipients can just reply to the emails and e.g. th:EmailtoTracScript can forward such replies to `10044@trac-hacks.org` to [th:ticket:10044 the appropriate ticket]):
+{{{#!python
+from trac.core import Component, implements
+from trac.config import Option
+from trac.notification.api import IEmailDecorator
+from trac.notification.mail import set_header
+
+class ReplyToTicketDecorator(Component):
+    """Replaces the 'Reply-To' header for tickets with a dynamic email address.
+
+    Uses a new config option 'ticket_smtp_replyto'.
+    """
+    implements(IEmailDecorator)
+
+    ticket_smtp_replyto = Option('notification', 'ticket_smtp_replyto', '__id__@localhost',
+                """Reply-To address for ticket notification emails.
+
+                   ` __id__` is replaced with the ticket id.""")
+
+    def decorate_message(self, event, message, charset):
+        if event.realm == 'ticket':
+            replyto = self.ticket_email_replyto.replace('__id__', str(event.target.id))
+            set_header(message, 'Reply-To', replyto, charset)
+}}}
+
+== Available Implementations ==
+
+* [source:trunk/trac/notification/mail.py#/AlwaysEmailDecorator trac.notification.mail.AlwaysEmailDecorator]: Implements `smtp_always_cc` and `smtp_always_bcc` configuration options.
+
+== Additional Information and References ==
+
+ * [apiref:trac.notification.api.IEmailDecorator-class epydoc]
+ * [apidoc:api/trac_notification#trac.notification.api.IEmailDecorator API Reference]
+
+=== History
+ * This interface originated in th:AnnouncerPlugin as `IAnnouncementEmailDecorator`.
+ * [wiki:TracDev/ApiChanges/1.1.3#IEmailDecorator 1.1.3]: Integrated `IEmailDecorator` in Trac as part of [wiki:TracDev/Proposals/AdvancedNotification this proposal] (#3517)
+   * Removed continuation-passing style (`next_decorator()`).
+   * Added `charset` parameter.