`gs.group.list.email.html`¶

Author:	Michael JasonSmith
Contact:	Michael JasonSmith <mpj17@onlinegroups.net>
Date:	2015-07-10
Organization:	GroupServer.org
Copyright:	This document is licensed under a Creative Commons Attribution-Share Alike 4.0 International License by OnlineGroups.Net.

Contents:

Message template¶

The HTML form of the message is formatted using the standard HTML-email templates [1]. The content is provided by two viewlet managers [2]: one for the pre-roll and one for the main html message.

┌─HTML message─────────────────────────────────────────┐
│                                                      │
│  ┌─Pre-roll viewlet manager────────────────────────┐ │
│  │ gs.group.list.email.html.interfaces.IPreroll    │ │
│  └─────────────────────────────────────────────────┘ │
│                                                      │
│ ┌─HTML message viewlet manager─────────────────────┐ │
│ │ gs.group.list.email.html.interfaces.IHTMLMessage │ │
│ │                                                  │ │
│ │ ┌─Prologue viewlet─────────────────────────────┐ │ │
│ │ │ gs-group-list-email-html-prologue            │ │ │
│ │ └──────────────────────────────────────────────┘ │ │
│ │                                                  │ │
│ │ ┌─Body viewlet─────────────────────────────────┐ │ │
│ │ │ gs-group-list-email-html-body                │ │ │
│ │ └──────────────────────────────────────────────┘ │ │
│ │                                                  │ │
│ │ ┌─Files viewlet────────────────────────────────┐ │ │
│ │ │ gs-group-list-email-html-files               │ │ │
│ │ └──────────────────────────────────────────────┘ │ │
│ │                                                  │ │
│ └──────────────────────────────────────────────────┘ │
│                                                      │
│ ┌─Links viewlet────────────────────────────────────┐ │
│ │ gs-group-list-email-html-links                   │ │
│ └──────────────────────────────────────────────────┘ │
│                                                      │
└──────────────────────────────────────────────────────┘

Pre-roll¶

The pre-roll part of an HTML message is unformatted hidden text that is slotted before the rest of the message. It is picked up by email clients that use it for a summary (or preview) of the message: think of it like a second subject-line.

The viewlet manager groupserver.EmailHTMLPreroll (gs.group.list.email.html.interfaces.IPreroll) is normally filled by the File notice viewlets.

The File notice viewlets state that there is one or more files listed in the files viewlet:

One (gs-group-list-email-html-preroll-file) provides a short notice that there is a file listed in the appendix of a message,
The other (gs-group-list-email-html-preroll-files) provides a short notice that there are multiple files listed in the appendix of a message.

There is also a summary provided when there are no files present (gs-group-list-email-html-preroll-nofile). It just spells out the origin of the message (the site and group names).

HTML message¶

The HTML message viewlet manager groupserver.EmailHTML (gs.group.list.email.html.interfaces.IHTMLMessage) provides the bulk of what people see in the message. There are three viewlets shipped by default: a prologue, the body proper, and the files.

Prologue¶

The prologue of a message appears at the top of the message body, before the body proper. The prologue contains the metadata for the post:

Who made the post (name and photo),
The group the post was made to, and
The topic the group was made to.

It also provides many links to the profile, group, and topic respectively.

Body¶

The Plan body (gs-group-list-email-html-body-plain) viewlet writes out the body of the post much as it was when it was sent in. It is currently the text version of the message, with newlines replaced with <br /> elements. Like the post on the web, bottom-quoting is removed (replaced with a link to the post).

Files¶

Files are large burden for a list, as they dramatically increase the size of the message for little gain. Because of this the attached files are replaced with links to the files on the Web. The Files list viewlet (gs-group-list-email-html-files) provides this list.

Links¶

The Links (gs-group-list-email-html-links) are a group of HTTP and mailto links to perform some common functions. The first three links are rendered as buttons, while the last two are rendered as normal links.

Reply:

The Reply link provides a mailto URI to send an email to the group with a nice tidy Subject header. The link is mostly there to stop the New topic link from being confusing: without the Reply it looks as if you can only start topics. The link is only shown if the reply-to setting for a group is group (the default).

New topic:

Most people are happy replying to a group using the Reply button in their email client. However, many are unaware that they can start topics. To combat this the New topic link provides a mailto URI to email the group. (Unusually for a GroupServer mailto URI the Subject is blank.) The New topic link is hidden if the reply-to setting for a group is author.

Topic:

The Topic link is an HTTP-link to the topic page, just like the topic-title in the Prologue.

Unsubscribe:

As required by legislation, the Unsubscribe link removes a person from a group. The link contains a mailto URI that sends a message to the group, with the the Subject header set to Unsubscribe. A mailto URI is used — rather than sending the person to the Leave page — so passwords do not have to be used.

The Unsubscribe email command is processed by gs.group.member.leave.command

Daily digest:

A handy link copied from our friends at E-Democracy.org, the Digest a mailto URI that points to the group with the Subject header set to Digest on.

The Digest on command is processed by gs.group.member.email.settings.

[1]	See the `gs.content.email.layout` product <https://github.com/groupserver/gs.content.email.layout>

[2]	See the `zope.viewlet` product <https://pypi.python.org/pypi/zope.viewlet/>

Adaptor¶

The message.HTMLMessagePart class adapts a post (as the context) and a browser request, and provides the gs.group.list.email.base.interfaces.IMessagePart interface.

The message.HTMLMessagePart.show property returns True if the HTML-form of a message should be shown. It looks up the htmlEmail property in the DivisionConfiguration and the GlobalConfiguration objects, with the setting in the former overriding the latter. If the htmlEmail property is absent then the default action is taken: show HTML email.

The message.HTMLMessagePart.as_email() method returns an instance of the standard email.mime.text.MIMEText class, with the MIME-type set to text/html. The UTF-8 character-encoding is set.

Changelog¶

TODO: 2.0.0 (yyyy-mm-dd)¶

Using the HTML form of an email if present

1.2.0 (2015-10-30)¶

Moving the HTMLBody and Matcher classes to gs.group.messages.text

1.1.4 (2015-10-13)¶

Following the changes to gs.group.messages.post.text
Using the mailto function from gs.core

1.1.3 (2015-09-28)¶

Adding an align="left" for the body of the message

1.1.2 (2015-09-24)¶

Dropping the Reply and New topic links as required by the Reply-to setting for a group
Updating the documentation

1.1.1 (2015-09-21)¶

Fixing the Subject header, lowering the case for Google GMail

1.1.0 (2015-09-16)¶

Allowing HTML formatted messages to be turned off on a site and install basis

1.0.0 (2015-09-08)¶

Initial version. Prior to the creation of this product there were no HTML formatted text messages.

The email messages that GroupServer sends from a group are different from what is received. This product supplies a a message template for rendering a post in HTML, and an adaptor for displaying the HTML version of the post in an email message.

Resources¶

Code repository: https://github.com/groupserver/gs.group.list.email.html
Questions and comments to http://groupserver.org/groups/development
Report bugs at https://redmine.iopen.net/projects/groupserver

gs.group.list.email.html¶