Magnolia Newsletter module connects Magnolia to an external newsletter service like Campaign Monitor. You can create your newsletter pages in the STK and import them into the external service.

The module provides an API to connect to the external service and a default configuration for Campaign Monitor is included. You can add API keys directly in the module configuration, and create subscribe and unsubscribe forms. The email addresses collected on your site are automatically transferred to the email lists maintained at the external service.

The Newsletter module relies on the Form module to create the necessary forms. Newsletter pages can have a different CSS or even a completely different content structure using Magnolia's sub-template mechanism. Magnolia International uses the Newsletter module to send their newsletter. Compare Magnolia's newsletter on the web with the version used to send the actual newsletter.

Download

The Newsletter module is not bundled with Magnolia and need to be downloaded and installed separately.You can download it from our Nexus repository

Installing

Newsletter is a Enterprise Edition module. It is typically not installed. Launch the Configuration app and go to /modules/newsletter, /newsletter-campaign-monitor and /newsletter-stk to check.

(warning) Create a backup of your system before you install a module. Uninstalling a module is not as simple as removing the .jar file. Modules add and change configurations and may change the content. Try new modules in a test environment first. A module consists of a JAR file and may include dependent JAR files. Modules are responsible for updating their own content and configurations across versions. Be sure to keep only one version of each module and its dependencies.

To install a module:

  1. Stop the application server.
  2. Copy the module JAR files into the WEB-INF/lib directory. The location of this directory depends on the application server.
    • Tomcat: /webapps/magnoliaAuthor/WEB-INF/lib
    • JBoss: /server/default/deploy/magnoliaAuthor/WEB-INF/lib
  3. Restart the server.
  4. Go to the AdminCentral URL.
  5. Start the Web update process.
  6. Click Start up Magnolia.

Repeat the steps for each author and public instance.

Uninstalling

To uninstall a module, remove the module JAR file from the /WEB-INF/lib folder and restart Magnolia.

(warning) However, this is rarely enough. Modules add and modify configuration during installation. The use of a module also changes content. Removing all of these changes is difficult without knowing the installation tasks in detail.

To test a module, use the embedded Derby database and take a backup of your repositories folder. Install the module and try it. When you are done testing, remove the module JAR and restore the repositories folder from the backup. This way you can go back to square one.

We also recommend that you segregate the development and production environments. Take regular backups for disaster recovery so you can revert to a prior state in a routine fashion.

Configuration

The module adds three sub modules in /modules:

  • newsletter: Interface to be implemented for your external emailing service. For Campaign Monitor the required nodes are:
    • apiKey: Generated by Campaign Monitor.
    • class: Class that implements the service. HttpSubscriber (Git) is the SubcriberService implementation for HTTP-GET protocol
    • clientId: Generated by Campaign Monitor.
    • defaultListId: Generated by Campaign Monitor.

For more information see Campaign Monitor - API Documentation.

  • newsletter-campaign-monitor: Implements the Newsletter module API for use with your Campaign Monitor account and requires no configuration.
  • newsletter-stk: Makes the implementation available in the STK by adding STK components and dialogs (see below).

Node name

Value

 modules

 

 newsletter

 

 config

 

 subscriptionService

 

 apiKey

f1c1f74b31ae627f5c320a735251aa9d

 class

info.magnolia.newsletter.campaignmonitor.HttpSubscriber 

 clientId

78e814111036e8eae06bac44b4e09d0f 

 defaultListId

f523148b05227023f1c7baa2acc93c1a

 version

 2.0.0

 newsletter-campaign-monitor

 

 newsletter-stk

 

Components

The Newsletter STK module includes two custom form components that allow users to subscribe and unsubscribe from mailing lists managed in Campaign Monitor. As newsletters are required to contain an unsubscribe link, the unsubscription component is of less relevance. You can view the components on the demo-features/modules/newsletter page.

Component definitions

The stkNewsletterSubscribe and stkNewsletterUnSubscribe components are configured at /modules/newsletter-stk/templates/components.The components extend the Form component and override the standard form processors. Two custom form processors are provided:

  • SubscribeFormProcessor (Git): Uses the Newsletter module API to perform a subscribe action. Form fields with specific names are expected:
    • email: Mandatory field for a valid email address.
    • displayName: Optional field for a user nickname.
  • UnsubscribeFormProcessor (Git): Uses the Newsletter module API to perform an unsubscribe action. Form field with a specific name isexpected:
    • email: Mandatory field for a valid email address.

Here's the definition for the stkNewsletterSubscribe component.

Node name

Value

 modules

 

 newsletter-stk

 

 templates

 

 components

 

 stkNewsletterSubscribe

 

 formProcessors

 

 subscribeNewsletter

 

 class

info.magnolia.newsletter.form.SubscribeFormProcessor

 enabled

 true

 extends

 override

 areas

 

 description

paragraphs.newsletter.subscribe.description

 dialog

newsletter-stk:stkNewsletterSubscribe 

 extends

/modules/form/templates/components/form 

 i18nBasename

info.magnolia.newsletter.messages 

 title

paragraphs.newsletter.subscribe.title 

 stkNewsletterUnSubscribe

 

Dialogs

The dialogs referenced by the newsletter component definitions are configured at /modules/newsletter-stk/dialogs/stkNewsletterSubscribe and /stkNewsletterUnSubscribe. The dialogs are identical and contain three tabs:

  • tabMain: A standard Form tab. See Configuring form settings for more information.
  • tabSubmit: A standard Submit settings tab. See Configuring form settings for more information.
  • tabCM: Contains the listId field that provides a dropdown of subscription lists set up in Campaign Monitor. This field uses a uses a custom field definition class, NewsletterSelectorDefinition (Git), that extends the Select field definition, and gets the Campaign Monitor subscription lists.

Node name

Value

 newsletter-stk

 

 dialogs

 

 stkNewsletterSubscribe

 

 actions

 

 form

 

 tabs

 

 tabMain

 

 tabSubmit

 

 tabCM

 

 fields

 

 listId

 

 class

info.magnolia.newsletter.field.NewsletterSelectorDefinition

 label

dialogs.newsletterSubscribe.tabCM.listId.label 

 label

dialogs.newsletterSubscribe.tabCM.label 

 i18nBasename

info.magnolia.newsletter.messages 

 label

dialogs.newsletterSubscribe.label 

 stkNewsletterUnSubscribe

 

Here's the stkNewsletterSubscribe dialog.

Making components available

The Newsletter STK module makes the newsletter components available in content area in the stkSection template at STK > Template Definitions /pages/stkSection/areas/main/areas/content/availableComponents. You can make the components available on any STK template.

Node name

Value

 pages

 

 stkSection

 

 areas

 

 main

 

 areas

 

 content

 

 availableComponents

 

 stkTeaser

 

....

 

 stkNewsletterSubscribe

 

 id

newsletter-stk:components/stkNewsletterSubscribe

 stkNewsletterUnSubscribe

 

 id

newsletter-stk:components/stkNewsletterUnSubscribe
#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))

To comment, create an account and log in.

© Copyright 2023 Magnolia