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

def notify_user(obj, event):
    """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.
    """
    
    # Check if user notification is enabled
    registry = queryUtility(IRegistry)
    settings = registry.forInterface(IDiscussionSettings, check=False)
    if not settings.user_notification_enabled:
        return
    
    # Get informations that are necessary to send an email
    mail_host = getToolByName(obj, 'MailHost')
    portal_url = getToolByName(obj, 'portal_url')
    portal = portal_url.getPortalObject()
    sender = portal.getProperty('email_from_address')

    # Check if a sender address is available
    if not sender:
        return

    # Compose and send emails to all users that have add a comment to this
    # conversation and enabled user_notification.
    conversation = aq_parent(obj)
    content_object = aq_parent(conversation)

    # Avoid sending multiple notification emails to the same person
    # when he has commented multiple times.
    emails = set()
    for comment in conversation.getComments():
        if (obj != comment and
            comment.user_notification and comment.author_email):
            emails.add(comment.author_email)
    
    if not emails:
        return
    
    subject = translate(_(u"A comment has been posted."),
                        context=obj.REQUEST)
    message = translate(Message(
            MAIL_NOTIFICATION_MESSAGE,
            mapping={'title': safe_unicode(content_object.title),
                     'link': content_object.absolute_url() + 
                             '/view#' + obj.id,
                     'text': obj.text}),
            context=obj.REQUEST)
    for email in emails:
        # Send email
        try:
            mail_host.send(message,
                           email,
                           sender,
                           subject,
                           charset='utf-8')
        except SMTPException:
            logger.error('SMTP exception while trying to send an ' +
                         'email from %s to %s',
                         sender,
                         email)

Moderator Notification

plone/app/discussion/comment.py

def notify_moderator(obj, event):
    """Tell the moderator when a comment needs attention.
       
       This method sends an email to the moderator if comment moderation a new 
       comment has been added that needs to be approved.
       
       The moderator_notification setting has to be enabled in the discussion
       control panel.
       
       Configure the moderator e-mail address in the discussion control panel.
       If no moderator is configured but moderator notifications are turned on,
       the site admin email (from the mail control panel) will be used.
    """
    # Check if moderator notification is enabled
    registry = queryUtility(IRegistry)
    settings = registry.forInterface(IDiscussionSettings, check=False)
    if not settings.moderator_notification_enabled:
        return
    
    # Get informations that are necessary to send an email
    mail_host = getToolByName(obj, 'MailHost')
    portal_url = getToolByName(obj, 'portal_url')
    portal = portal_url.getPortalObject()
    sender = portal.getProperty('email_from_address')
    
    if settings.moderator_email:
        mto = settings.moderator_email
    else:
        mto = sender
    
    # Check if a sender address is available
    if not sender:
        return
    
    conversation = aq_parent(obj)
    content_object = aq_parent(conversation)
    
    # Compose email
    subject = translate(_(u"A comment has been posted."), context=obj.REQUEST)
    message = translate(Message(MAIL_NOTIFICATION_MESSAGE_MODERATOR,
        mapping={
            'title': safe_unicode(content_object.title),
            'link': content_object.absolute_url() + '/view#' + obj.id,
            'text': obj.text,
            'link_approve': obj.absolute_url() + '/@@moderate-publish-comment',
            'link_delete': obj.absolute_url() + '/@@moderate-delete-comment',
            }),
        context=obj.REQUEST)
    
    # Send email
    try:
        mail_host.send(message, mto, sender, subject, charset='utf-8')
    except SMTPException, e:
        logger.error('SMTP exception (%s) while trying to send an ' +
                     'email notification to the comment moderator ' +
                     '(from %s to %s, message: %s)',
                     e,
                     sender,
                     mto,
                     message)

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/app/discussion/notifications.zcml

<configure
    xmlns="http://namespaces.zope.org/zope"
    xmlns:zcml="http://namespaces.zope.org/zcml"
    i18n_domain="plone.app.discussion">

  <subscriber
      for="plone.app.discussion.interfaces.IComment
           zope.app.container.interfaces.IObjectAddedEvent"
      handler=".comment.notify_user"
      />

  <subscriber
      for="plone.app.discussion.interfaces.IComment
           zope.app.container.interfaces.IObjectAddedEvent"
      handler=".comment.notify_moderator"
      />

</configure>