| Plugin Newsletter |
Authors | Anyware Services |
Most recent version | 1.5.0 |
Tracking issues | |
Download | Lastest version |
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. | 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
|
|
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.
|
|
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.x | 1.5.x |
Ametys 3.0.x |
|
|
|
| ||
Ametys 3.1.x |
|
|
|
| ||
Ametys 3.2.x |
|
|
|
| ||
| Ametys 3.3.x |
| |||||
| Ametys 3.4.x |
|
Back to top