NewsletterLiferayPlugin

Newsletter plugin by zylk.net

Description

This is a plugin for Liferay that allows for a fully integrated newsletters system in the portal. The generated newsletters can include any content hosted on the portal (forum, blog, articles ...) and its appearance can be fully customized. It is also possible to schedule mailing so this process is performed automatically.

Features

  • Powefull template engine. The template engine is integrated with Liferay's journal template system, so it's possible to:
    • Completely customize the appearance of the newsletters.
    • Include any portal content (blog post, forum, ...) in the newsletters.
  • Subscription / Unsubscription system (with email confirmation). Users can subscribe themselves to the newsletters from one page set up for this purpose in the portal. And is also possible to manage subscribers from the plugin admin panel.
  • I18n. The plugin is translated into multiple languages, and provides support for the translation of the newsletters.
  • Multi-Site support. Each Site can manage their own newsletters, and management can be performed independently on each Site.
  • Scheduler. The newsletters can be scheduled (daily, weekly, monthly …) to be sent automatically.
  • Category management. You can manage different categories so that users can subscribe to different topics.
  • Import users from CSV. So that you can import existing users in external systems.
  • Mailing history. From the Mailing section (history) you can check all the information of emails already sent.

Road map

  • Advanced integration with portal users.
  • Email tracking and analytics.

Notes

  • The plugin has been developped by zylk.net in collaboration with Izfe.
  • The plugin is open software (AGPL), free and features are not restricted.
  • The Marketplace plugin is for Liferay 6.2, but we have also a version available for liferay 6.1, so if you want to try let us know.
  • If you find any error, want to suggest any improvement, or want to colaborate in any way u can contact us through this link.

Examples

Here are some sample newsletters performed with the plugin:

An example showing 3 latest news of the portal:


Another example, this one is generated and sent automatically every month with last Blog posts of the portal:


Technical documentation

Installation

To install the plugin you only need to deploy the WAR in the standard way, copying the war in Liferay deploy directory.

The plugin has 3 portlets:

  • Administration Portlet: It is the administration portlet of the plugin.
  • User Subscription Portlet: Portlet with the public form where the user can subscribe to the newsletters.
  • Subscription Manager Portlet: This is the portlet that manages the subscription / unsubscription of the users, though not really have any visual component and can not interact with it. Its operation is managed internally by the plugin.

The Administration Portlet automatically appears in the Liferay control panel under the category Content. The other two portlets must be included manually on the public pages of the site. So:

  1. Create the page where want to put the subscription form and include on that page the User Subscription Portlet.
  2. Create another page called subscription (can have the name you prefer) and include on that page the Subscription Manager Portlet. This page is recommended to be hidden to prevent it from appearing in the portal menu.

Once this is done the plugin is already fully installed. Although for use in production is first necessary to configure some basic aspects detailed in the following section.

General configuration

In the first instance we will configure the general parameters of the plugin. So go to the administration portlet and click in the configuration wheel.


As can be seen there are two tabs available: Global properties and Subscription email.


Global properties

  • Site Url: It is essential to configure this url properly, otherwise the unsubscription links included in the newsletters will not work correctly (default value is localhost).
  • Email from name: Sender's name for newsletter mailing. If left empty the default value defined in the portal will be set.
  • Email from address: Sender's address for newsletter mailing. If left empty the default value defined in the portal will be set.


Subscription email

You can configure the following fields:

  • Subject: Subject of subscription email.
  • Body: Content of subscription email.

In both cases you may use the following variables:

Terms definition

[$SUBSCRIPTOR_NAME$] Subscriber name.
[$SUBSCRIPTOR_SURNAME$] Subscriber surname.
[$SUBSCRIPTOR_FULLNAME$] Full name (name and surname) of the subscriber.
[$SUBSCRIPTOR_EMAIL$] Subscriber email.
[$SUBSCRIPTION_URL$] Subscription confirmation url.


Create new category

After configuring the general parameters its necessary to create a category (or topic). So go to Categories tab and press the Create new category button.

Create new subscriber

Once the category is created, we can create a subscriber. Subscribers can be created in two ways. On the one hand it is possible to create subscribers from the administration portlet, and on the other hand the users can subscribe themselves through User Subscription Portlet. In this case we will create a subscriber from the administration portlet.


Therefore go to the "Subscribers" section, click on the button Create new subscriber and introduce suitable data (selecting the category created earlier).

It is also possible to import external users through CSV file. To do this click on the Import from CSV button and upload a file. The file must comply with the pattern detailed on the screen.

Configure new newsletter

Having done the above we already have a category and a subscriber, so now we can configure the newsletter. So let's go to the newsletter tab and click Configure new newsletter.


The form of the newsletter creation will be displayed.


As you can see the neswletter has the fields described below.


General

  • Name (Required): It is a descriptive name of the newsletter.
  • Description: Additional description of the newsletter.
  • Category: Category to which belongs the newsletter. The newsletter will be sent only to users subscribed to that category.


Content

  • Subject (Requerido): It is the subject of the email.
  • Artícle: The content of the newsletter is constructed through a Web Content article (journal), so at this point we only have to select an article previously created in Liferay Web Content manager. Keep in mind that only those who have the tag 'newsletter' will be shown. The plugin automatically imports 2 web contents as examples:
    • Newsletter - Blog summary: This article shows the last post of the Blog. To work properly some blog post must be created before.
    • Newsletter - Dark 1-2 columns: This article sample 3 featured content.

This feature is explained more extensively in Newsletter design point.

Important: For these examples work correctly you need to set velocity.engine.restricted.variables property from portal-ext.properties as follows:

velocity.engine.restricted.variables=


Scheduler

  • Enable scheduler: Enable or disable the scheduler.
  • Frequency: Where the frequency of sending the newsletter stated. You are allowed to choose between Daily, Weekly, Monthly, or Specific day.


After configuring a new newsletter, we can do the following actions in the list of newsletters:

  • Edit: Edit the configuration of the newsletter.
  • Preview. Displays a preview of the newsletter. It is important to note that the preview does not have to agree 100% with the end result to be sent to users. So it is recommended to test the newsletter by sending it and checking the result in the email client.
  • Send: This action sends the newsletter at that moment.
  • Delete: Removes the configuration of the newslerter.


Mailing

Finally from the Mailing section you can access all newsletters sent and check their details.

Public subscription (User Subscription Portlet)

As mentioned above users can subscribe themselves through User Subscription Portlet. User Subscription Portlet once deployed on a page looks like this (since it is in the public part of the Site the final appearance will depend on the theme used).


After entering the data and clicking the Ok button an email will be sent to confirm the subscription.

Furthermore unsubscription is managed in the newsletter email itself. That is, in each newsletter email sent will be a link from which the user can start the process of unsubscription.


Newsletter design

As mentioned above the plugin is integrated with the Web Content Manager of Liferay (journal), so it is necessary to have some knowledge of it. This integration allows to use the power of Liferays template system for generating the newsletters. As you know from the Liferay Web Content templates you can completely customize the look and feel and access any portal content, so the possibilities when designing the newsletters are endless. At the moment the plugin only works with velocity template language.

Therefore to define the content of the newsletter, create a Web Content article (with an associated Web Content template) and assign it to the newsletter in the field Content -> Artícle.

The plugin imports two examples:

  • Newsletter - Blog summary: This article shows the last post of the Blog. To work properly some blog post must be created before.
  • Newsletter - Dark 1-2 columns: This article sample 3 featured content.

These Web articles and templates are imported into the global scope, so they are accessible from any Site of the portal. If the content and templates are stored in a particular Site, they will only be visible at that Site.

In velocity templates you can use the following variables.

Terms definition

@subscriptor_name@ Subscriber name.

@subscriptor_surname@ Subscriber surname.

@subscriptor_fullname@ Full name (name and surname) of the subscriber.

@subscriptor_email@ Subscriber email.

@unsubscribe_url@ Un-subscription url

@start_date_ms@ Date of execution of the newsletter (or date set on the scheduler).

@from_date_ms@ Previous date of the period set in the scheduler.

@cancel_mailing@ It is a special key. If this key is included in the template the newsletter mailing will be canceled.

  • Dates are expressed in milliseconds (java).
  • The key @cancel_mailing@ is used to be able to cancel the mailing of the newsletter from the implementation of the template. So if we want to cancel the mailing for whatever reason (because there is no new content for example), we only need to include this token as result of the processed template.


Important: In order to use all liferay services in velocity templates, you need to set velocity.engine.restricted.variables property from portal-ext.properties as follows:

velocity.engine.restricted.variables=

Tips

  • Keep in mind that email clients only support a limited set of html. So it is important to check the results in multiple clients to make sure everything works as expected.
  • You can use the Preview action to test the results, but it is important to note that the preview does not have to agree 100% with the end result to be sent to users. So it is recommended to test the newsletter by sending it and checking the result in the email client.


Advanced configuration

The plugin has a configuration file through which you can modify the behavior of some features.

portlet.properties

# Habilitar el sistema de envio de mails en la misma session. Sino utiliza el sistema de liferay. 
zn.email.system.session.handler.enable=false

# Limite de correos por sesion
zn.email.system.session.email.limit=25

# Tiempo de espera entre sesion y sesion (expresado en milisegundos)
zn.email.system.session.wait.time=10000

# Url por defecto del portal (se pueden configurar por site desde la administracion).
zn.portal.url.default=http://localhost:8080

# Hora en el que se realizan los envios. Formato HH:mm (default TimeZone).
zn.scheduler.send.time=14:00

# Habilitar el importador de recursos (plantillas de ejemplo)
zn.import.default.resources.enable=true


Limit of emails per session

With the property zn.email.system.session.handler.enable you can limit the number of emails sent per session. This feature can be useful if the amount of newsletters to be sent is high (high number of subscribers) and the mail server used has restrictions in this regard.