Plugin Newsletters


newsletter_48.png

Plugin Newsletter
Extension to create and send newsletters to visitors

Authors

Anyware Services

Most recent version

1.5.0

Tracking issues

https://issues.ametys.org/browse/NEWSLETTER

Download

Lastest version 

  1. Presentation
  2. Screenshots

Presentation

This extension allows to create newsletters for your visitors.

Features :

- newsletters classified by categories

- a layout of each categories of letters

- service subscription  to the newsletter with captcha

- service to view the archives 

- subscribers by category

- view and export (to excel format) of the subscribers

- sends the letter both in HTML and plain text format

- automatic insertion of the last published contents in the letter

- automatic summary with anchors constructs from newsletter section

- unsubscription by a single token

The newsletter content type is composed by the following fields :

Field

Type

Description

Mandatory

title

text

The title of the newsletter. This title is used in the mail subject

yes

number

decimal

The number of the newsletter. This number can be displayed on newsletter header

no

date

date

The newsletter date. This date is NOT responsible for the newsletter publication or sending.
It can be used on newsletter header for example

no

content

rich text

The newsletter full content

yes

Screenshots

User manual

Newsletter categories

The categories are defined for each site and each language.

There are 2 types of categories:

  • The personalized categories: these categories are created by the webmaster. They include a name and description. Each category can contain sub-categories.
  • The categories related to sections of the site taggued as newsletter's category: these categories are automatically calculated based on sections of the site. These categories have the name of the section to which they are attached. To make an page corresponds to a newsletter category, it must be tagged with the tag "Newsletter's category". This category is not editable and does not accept sub-category.


NewsletterTree.PNG

Create a new category

Open the tool Newsletter.

Select the parent category in the tree.

Click on button "New category"

CategoryAction.PNG

Enter a title and an optional description


EditCategory.PNG

Category and template

Each category must be assigned a template (layout). This template will be affected to all newsletter of this category.

It is possible to change the template of a category at any time.

Select the template in the menu "Template"


Newsletter-Template.png

A newsletter can be added to a category only if the category have an associated template

Add and edit a newsletter

Select the newsletter category and click on "Add newsletter" button


AddNewsletter.PNG

Enter the newsletter title and click 'OK' to enter in edition


AddNewsletter2.PNG

The letter is composed by :

  • a title
  • a number (optional)
  • a date (optional)
  • a rich content

The letter content is pre-filled by its category template defined by the integrator.

Insert last publication

You can simply insert the last publication in your newsletter.

1. Click on "Insert last publication" button.

2. In the assistant first step, restrict the search for last publication by the proposed criteria (title, type of contents, validation date, tags, page).

3. Click on "Next" button to launch search

4. Select the content to insert in the search result list

5. Click on "Ok" button to insert the selected content. An abstract of the selected content with a link "read more" will be inserted


InsertLastPublication.PNG


InsertLastPublication2.PNG

You are free to modify the inserted text.

Send the newsletter

The newsletter is sent when you validate it.


SendNewsletter.png

A confirmation message will be displayed. Click 'OK' to send the letter to all subscribers.


SendNewsletterConfirm.PNG

You can edit the letter and re-validate it as many time you need. If the letter was already sent, you can choose to validate it and sent it again or only validate it.

SendNewsletterConfirm2.PNG

Answer 'No' to only validate the newsletter, or 'Yes' to sent it again.

Subscription to the newsletter

This extension brings a service to offer the visitors to subscribe to a newsletter.

1. Go to "Add service" menu

2. Choose the service "Subscription to the newsletter"

SendNewsletter.png

3. In service parameters, select the newsletter category to subscribe to.


NewsletterServiceParameters.png


NewsletterServiceParameters2.png

Newsletter archives

This extension brings a service to list the newsletter archives.

1. Go to "Add service" menu

2. Choose the service "Newsletter archives"

3. In service parameters, select the newsletter category and the number max of records


NewsletterArchives.PNG

Newsletter's subscribers

From the Newsletter tool, you can see the list of subscribers for each category of newsletter :


Subscriber_List_EN.PNG

The list can be exported to format XLS (excel).

Import subscribers list (version 1.4+)

Since version 1.4+, you can import a list of subscribers from a TXT or CVS file.

The file must contain one email address by lines as the following example :


Import_File.PNG

Clic on "Import" button and select the file on your hard drive :


Import_Subscribers_EN.PNG

If you want to empty the list before import, check the box "Remove the existing subscribers".

Installation and download

Download

Installation

  • Add the plugin JAR in the WEB-INF/lib directory of your Ametys application.
  • In the WEB-INF/param/cms-ribbon.xml file, you have to add the buttons and contextual tab related to newsletters.

In home tab, add the button of id org.ametys.newsletter.userinterface.Newsletters. This button allows to open the newsletter tool.

<group label="RIBBON_TABS_TAB_HOME_GROUPS_GROUP_ADVANCED_TOOL_LABEL" icon="">
       <large></large>
       <medium>
            <control id="org.ametys.newsletter.userinterface.Newsletters"/>
            <layout size="small">
                 <control id="org.ametys.datainclusion.tool.DataSources"/>
                 <control id="org.ametys.web.userinterface.Alias"/>
            </layout>
       </medium>
       <small/>
 </group>
On CMS 3.0

Copy/paste the contextual tab "RIBBON_TABS_TAB_NEWSLETTER_CATEGORIES_LABEL" below at the end of the file. This contextual tab contains the action buttons related to the newsletter (add, edit, delete categories or newsletter, subscribers export)

<tab label="RIBBON_TABS_TAB_NEWSLETTER_CATEGORIES_LABEL" id="org.ametys.newsletter.NewsletterTab" contextualColor="6" contextualGroup="N" contextualLabel="RIBBON_TABS_TAB_NEWSLETTER_LABEL">
            <groups>
                <group label="RIBBON_TABS_TAB_NEWSLETTER_GROUPS_GROUP_HANDLE_LABEL" icon="">
                    <large></large>
                    <medium>
                        <control id="org.ametys.newsletter.addnewsletter"/>
                    </medium>
                    <small></small>
                </group>
                <group label="RIBBON_TABS_TAB_NEWSLETTER_GROUP_CATEGORIES_LABEL" icon="">
                    <large/>
                    <medium>
                        <control id="org.ametys.newsletter.category.Add"/>
                        <control id="org.ametys.newsletter.category.Edit"/>
                        <control id="org.ametys.newsletter.category.Delete"/>
                        <control id="org.ametys.newsletter.templatesmenu"/>
                    </medium>
                    <small/>
                </group>
                <group label="RIBBON_TABS_TAB_NEWSLETTER_GROUP_SUBSCRIBERS_LABEL" icon="">
                    <large/>
                    <medium>
                        <control id="org.ametys.newsletter.Subscribers"/>
                        <control id="org.ametys.newsletter.subscribers.Export"/>
                    </medium>
                    <small/>
                </group>
            </groups>
        </tab>

Add the i18n key into the application_*.xml files ?:

application_fr.xml

<message key="RIBBON_TABS_TAB_NEWSLETTER_LABEL">Lettre d\'information</message>
 <message key="RIBBON_TABS_TAB_NEWSLETTER_CATEGORIES_LABEL">Catégories</message>
 <message key="RIBBON_TABS_TAB_NEWSLETTER_CONTENT_LABEL">Newsletter</message>
 <message key="RIBBON_TABS_TAB_NEWSLETTER_GROUPS_GROUP_HANDLE_LABEL">Lettre d\'information</message>
 <message key="RIBBON_TABS_TAB_NEWSLETTER_GROUP_CATEGORIES_LABEL">Catégories</message>
 <message key="RIBBON_TABS_TAB_NEWSLETTER_GROUP_SUBSCRIBERS_LABEL">Abonnés</message>
 <message key="RIBBON_TABS_TAB_NEWSLETTER_LABEL">Newsletter</message>

application_en.xml

<message key="RIBBON_TABS_TAB_NEWSLETTER_LABEL">Newsletters</message>
 <message key="RIBBON_TABS_TAB_NEWSLETTER_CATEGORIES_LABEL">Categories</message>
 <message key="RIBBON_TABS_TAB_NEWSLETTER_CONTENT_LABEL">Newsletter</message>
 <message key="RIBBON_TABS_TAB_NEWSLETTER_GROUPS_GROUP_HANDLE_LABEL">Actions</message>
 <message key="RIBBON_TABS_TAB_NEWSLETTERCATEGORIES_LABEL">Newsletter categories</message>
 <message key="RIBBON_TABS_TAB_NEWSLETTERCATGEORIES_GROUP_LABEL">Newsletter categories</message>
 <message key="RIBBON_TABS_TAB_NEWSLETTERCATEGORIES_GROUP_ACTIONS_LABEL">Actions</message>

The newsletter use a content type, but this content type can not be used in a page, you so have to remove it from the "Add a new content menu". To do so : in the runtime.xml, for the single extension point
org.ametys.web.repository.page.ContentTypesAssignmentHandler choose the following value : org.ametys.plugins.newsletter.NewsletterContentTypeAssignmentHandler

On CMS 3.1 and Newsletter 1.1

Add the following to the end of your ribbon file

<!-- Newsletter contextual tabs -->
		<import>plugin:newsletter://cms-ribbon.xml</import>

The newsletter use a content type, but this content type can not be used in a page, you so have to remove it from the "Add a new content menu". To do so ensure the following content type id is not included org.ametys.plugins.newsletter.Content.newsletter
See https://wiki.ametys.org/display/AMETYSV3/Content+types#Contenttypes-Availablecontenttypesforthecontributor for more information.

On All versions
  • The newsletters have their own worflow (draf, proposed, validated). The validate action sends the newsletter to subscribers. Download the workflow description file for the newsletters to the following url : workflow-newsletter.xml. Copy it into the WEB-INF/paramsdirectory of your application. And modify the file workflows.xml to add the reference to this file using the name 'newsletter'.

    <workflows>
      <workflow name="content" type="file" location="workflow.xml"/>
      <workflow name="newsletter" type="file" location="workflow-newsletter.xml"/>
    </workflows>
    
  • Download and execute the "newsletter.sql" SQL script file, accessible to the following URLs according to your database :

Restart the servlet engine.

Integration

Create a newsletter template

This extension needs a graphical integration to create the newsletter template(s).

The reader must have a minimum of knowledge on these fields: HTML, CSS, XML, XSL, I18N.

For each template, you must create stylesheets (or XSL files) to generate the newsletter HTML page and text page.

Each template requires 2 xsl:template files, called 'template.xsl' for the HTML version and "template-text.xsl" for the text version.

These files are stored in the skin directory under 'skins/[MySkin]/newsletter/[MyTemplate]/stylesheets'

Sample of tempate.xsl file

<xsl:template match="/">
    <html>
       <head>
	    <xsl:copy-of select="/html/head/node()"/>
	    <link type="text/css" href="{$skincontext}/css/newsletter.css" rel="stylesheet" media="screen" />
	</head>

	<body>
	    <div id="email-box">

                  <div id="box">

                       <div id="header">
                            <!-- Header here (title, date, number, ...)-->
                       </div>

                       <div class="content">
                             <xsl:apply-templates select="/html/body/node()"/>
                       </div>

                        <div id="footer">
                            <!-- Footer here (mentions, unsubscribe, ...) -->
                       </div>

                  </div>
            </div>
	</body>
     </html>
</xsl:template>

Sample of tempate-text.xsl file

<xsl:template match="/">
   <html>
        <head>
	</head>

	<body>
<!-- Header -->
<xsl:text>---------------------------------------------------------------------------------------------------------</xsl:text><xsl:text>
</xsl:text>

		<xsl:apply-templates select="/html/body/node()"/>

<xsl:text>---------------------------------------------------------------------------------------------------------</xsl:text><xsl:text>
</xsl:text>
<!-- Footer (mentions, unsubscribe, ...) -->
	</body>

   </html>

</xsl:template>


<xsl:template match="h3"><xsl:text>
</xsl:text>. <xsl:value-of select="normalize-space(text())"/><xsl:text>
</xsl:text>
</xsl:template>

<xsl:template match="h2"><xsl:text>
</xsl:text><xsl:value-of select="translate(text(), 'abcdefghijklmnopqrstuvwxyz', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ')"/><xsl:text>
</xsl:text>
</xsl:template>

<xsl:template match="p"><xsl:apply-templates/><xsl:text>
</xsl:text>
</xsl:template>

<xsl:template match="br"><xsl:text>
</xsl:text>
</xsl:template>

<xsl:template match="img">[<xsl:value-of select="@alt"/>]
</xsl:template>

<xsl:template match="a"><xsl:value-of select="text()"/><xsl:text> </xsl:text><xsl:value-of select="@href"/>
</xsl:template>

<xsl:template match="text()"><xsl:value-of select="normalize-space(.)"/></xsl:template>

The following give you XSL code to insert an automatic summary, a link to see the newsletter on line and a link to unsubscribe to the newsletter :

Insert an automatic summary

<xsl:template name="toc">
        <xsl:if test="/html/body//div[@id = 'newsletter-content']/div[@class = 'center']/div[@class = 'articles']//h1">
            <div id="toc">
                <h2><i18n:text i18n:key="NEWSLETTER_TOP_OF_CONTENT" i18n:catalogue="skin.{$skin}"/></h2>
                
                <xsl:call-template name="toc-list"/>
            </div>
        </xsl:if>
 </xsl:template>
    
 <xsl:template name="toc-list">
       <ul>
            <xsl:for-each select="/html/body//div[@id = 'newsletter-content']/div[@class = 'center']/div[@class = 'articles']//h1">
                <li>
                    <a href="#go-to-{count(preceding::h1)}"><xsl:value-of select="text()"/></a>
                </li>
            </xsl:for-each>
        </ul>
 </xsl:template>
  

Link to unsubscribe to the newsletter

<a href="{$contextPath}/{$lang}/_plugins/newsletter/page/unsubscribe?token=#token#"><i18n:text i18n:key="NEWSLETTER_FOOTER_MENTIONS_4" i18n:catalogue="skin.{$skin}"/></a>

Link to see the newsletter online

<a href="{$contextPath}/_content/{/html/head/meta[@name = 'contentName']/@content}.html"><i18n:text i18n:key="NEWSLETTER_REDIRECT_2" i18n:catalogue="skin.{$skin}"/></a>
Create a newsletter model

A newsletter model is a XML file used to guide the webmaster while creating his newsletter. A new created newsletter content will be filled by this model.

There is a model for each newsletter template. The model is stored in directory skins/[MySkin]/newsletter/[MyTemplate]/model/model.xml'

This is a sample of model :

<model lang="en">
	<div id="newsletter-content">
		<div class="center">
			<div class="edito">
				<h1>Edito</h1>
				<p>
					Enter the edito here
				</p>
			</div>

			<div class="articles">
				<p>Insert the last publication here</p>
			</div>
		</div>

		<div class="sidebar">
			<div class="encart">
				<h2>Zoom</h2>
				<p>Enter the zoom here.</p>
			</div>

			<div class="encart last">
				<h2>Links</h2>
				<p>Enter the new links here</p>
			</div>
		</div>

	</div>
</model>
Override the newsletter content type

See the dedicated page on overriding content types (since Ametys 3.1, in Ametys 3.0 you have to duplicate the plugin)

For the following example, let's imagine you have add a subtitle metadata and you have add it also to the views

  • You can now get the subtitle value in the stylesheets/newsletter-*.xsl stylesheets

newsletter.xsl

<xsl:template match="/">
     <html>
        <head>
          [...]
          <meta name="subtitle" content="{/view/content/metadata/subtitle}" />
          [...]
        </head>
        <body>
          [...]
        </body>
     </html>
</xsl:template

In the newsletter template, the subtitle metadata will be accessible by the following XPath

<xsl:value-of select="/html/head/meta[@name = 'subtitle']/@content"/>

Configuration

The newsletter extension needs 3 configuration parameters :

  • Mail sender: the sender email (reply-to)
  • Automatic subscription to sub-categories : check the case to subscribers of category are automatically subscribed to its sub-categories.
  • Automatic subscription to  parent categories :check the case to subscribers of category are automatically subscribed to its parent categories.

Compatibility

Plugin version

1.0.x

1.1.x

1.2.x

1.3.x

1.4.x1.5.x

Ametys 3.0.x


tick_16.png

 

 

 

  

Ametys 3.1.x

 


tick_16.png

 

 

  

Ametys 3.2.x

 

 


tick_16.png


tick_16.png

  
Ametys 3.3.x    


tick_16.png

 
Ametys 3.4.x     


tick_16.png