Magnolia 4.5 reached end of life on June 30, 2016. This branch is no longer supported, see End-of-life policy.

Page tree
Skip to end of metadata
Go to start of metadata

Magnolia Newsletter module integrates Magnolia with 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. The integration allows you to 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 integrated with Campaign Monitor to send their newsletter. Compare Magnolia's newsletter on the web with the version used to send the actual newsletter.

Download

Download the Newsletter module from Magnolia Store or Nexus repository.

Installing

Newletter is an enterprise module (4.1 and higher) available in the add-ons folder of the Enterprise Edition bundle. To install the module, see the general module installation instructions.

Uninstalling

See the general module uninstalling instructions and advice.

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: Integrates the implementation with the STK by adding STK components and dialogs (see below).

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 in /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.

Dialogs

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

  • tabMain: A standard Form tab. See Form settings for more information.
  • tabSubmit: A standard Submit settings tab. See 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 control type, newsletterSelect. This control is registered in /modules/newsletter-stk/controls/newsletterSelect, and uses the NewsletterSTKDialogSelect class, that extends the Select control, and gets the Campaign Monitor subscription lists.

Here's the stkNewsletterSubscribe dialog.

Making components available

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