Changes between Version 4 and Version 5 of CookBook/Notification/Email

Timestamp:

Mar 12, 2017, 2:57:19 PM (7 years ago)

Author:

Peter Suter

Comment:

ListPrecedenceEmailDecorator and TicketFieldEmailDecorator

CookBook/Notification/Email

@@ -3 +3 @@
 
 TracNotification customizations can often be implemented with a short plugin. Some custom examples are given on this page.
+
+== Add or change email header
+Some projects like to add or change special email headers to notification emails.
+
+For example by default Trac sends notifications with email header `Precedence: bulk`, but some projects prefer to use `Precedence: list`:
+
+1. Create a [TracDev/PluginDevelopment#Singlefileplugins single file plugin] that implements [wiki:TracDev/PluginDevelopment/ExtensionPoints/trac.notification.api.IEmailDecorator IEmailDecorator]:
+{{{#!python
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2017 Edgewall Software
+# All rights reserved.
+#
+# This software is licensed as described in the file COPYING, which
+# you should have received as part of this distribution. The terms
+# are also available at http://trac.edgewall.org/wiki/TracLicense.
+#
+# This software consists of voluntary contributions made by many
+# individuals. For the exact contribution history, see the revision
+# history and logs, available at http://trac.edgewall.org/log/.
+
+from trac.core import Component, implements
+from trac.notification.api import IEmailDecorator
+from trac.notification.mail import set_header
+
+class ListPrecedenceEmailDecorator(Component):
+
+    implements(IEmailDecorator)
+
+    # IEmailDecorator methods
+    
+    def decorate_message(self, event, message, charset):
+        set_header(message, 'Precedence', 'list', charset)
+}}}
+
+See also: #7499
+
+== Add ticket fields to email headers
+Some projects need email headers with the current or changed values of ticket fields:
+
+1. Create a [TracDev/PluginDevelopment#Singlefileplugins single file plugin] that implements [wiki:TracDev/PluginDevelopment/ExtensionPoints/trac.notification.api.IEmailDecorator IEmailDecorator]:
+{{{#!python
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2017 Edgewall Software
+# All rights reserved.
+#
+# This software is licensed as described in the file COPYING, which
+# you should have received as part of this distribution. The terms
+# are also available at http://trac.edgewall.org/wiki/TracLicense.
+#
+# This software consists of voluntary contributions made by many
+# individuals. For the exact contribution history, see the revision
+# history and logs, available at http://trac.edgewall.org/log/.
+
+from trac.config import ListOption
+from trac.core import Component, implements
+from trac.notification.api import IEmailDecorator
+from trac.notification.mail import set_header
+
+class TicketFieldEmailDecorator(Component):
+
+    implements(IEmailDecorator)
+
+    smtp_x_trac_ticket_headers = ListOption('notification',
+            'smtp_x_trac_ticket_headers', 'CHANGED',
+            doc="""Possible values: ''ALL'', ''CHANGED'' or comma-separated
+            list of ticket properties.
+
+            Those properties are put into the e-mail headers when notifying
+            about ticket updates.""")
+
+    # IEmailDecorator methods
+    
+    def decorate_message(self, event, message, charset):
+        if event.realm != 'ticket' or event.category == 'batchmodify':
+            return
+        def header(value, *parts):
+            name = '-'.join(part.capitalize() for part in parts)
+            set_header(message, name, value, charset)
+        fields = list(self.smtp_x_trac_ticket_headers)
+        prefix = 'X-Trac-Ticket'
+        if fields == ['CHANGED']:
+            for item, change in event.changes['fields'].iteritems():
+                for type, value in change.iteritems():
+                    header(value, prefix, item, type)
+        elif fields == ['ALL']:
+            for item in event.target.values:
+                header(event.target.values[item], prefix, item)
+        else:
+            for item in fields:
+                header(event.target.values[item], prefix, item)
+}}}
+1. Set the configuration `[notification] smtp_x_trac_ticket_headers` to `ALL` or to a list of ticket field names.
+
+See also: #6516
 
 == Attachments in Notification Emails