Developers Guide¶

Introduction¶

The Newsletter Bundle from XROW GmbH allows developers to easily integrate newsletter functionality into their Ibexa applications. It offers support for popular platforms, with Maileon and Sendgrid currently supported, and can be easily extended to support other APIs.
The bundle also provides a possibility of subscribing to a Newsletter through a form, and adding a reCAPTCHA to the form to increase its security.

All configuration options can be set in the bundle's configuration file，please refer to the Settings section for details.

To quickly add support for a new Newsletter API, developers can extend the Xrow\NewsletterBundle\Adapter\NewsletterAdapterInterface.
This interface provides important methods related to handling newsletters such as:

send
test
subscribe
deleteCampaign
copyCampaign

By implementing these methods, developers can easily add support for a new API. The new provider must be activated by configuring the adapter option in the project's configuration.
For example, in your config/packages/newsletter.yaml file, activate a new adapter as follows:

xrow_newsletter:
    # The "app.mynewsletter" here needs to correspond to the service name defined in `config/services.yaml`.
    adapter: app.mynewsletter

This configuration variable xrow_newsletter.adapter is passed as an argument to a method (Xrow\NewsletterBundle\Factory\NewsletterFactory::createNewsletterAdapter) of a factory class.
The factory uses this argument to create an instance of the adapter and returns it. Therefore, by modifying this parameter xrow_newsletter.adapter, it can be determined which implementation of the adapter to create.

In config\services.yml, we define the service like this:

app.mynewsletter:
    class: App\Adapter\MyNewsletterAdapter
        public: true
        arguments:
            ...
        tags:
            - { name: monolog.logger, channel: mynewsletter }

First, we can create a "subscription form" template for the newsletter in the project, which can be named according to your preferences (Here, we temporarily name it registerform.html.twig), it can be placed in the project template directory (such as templates/themes/..).

The template should at least contain an <input> tag for filling in the email address used for registration and a submit button to submit the form. If you need to add other <input> tag, you need to override the logic of Xrow\NewsletterBundle\Controller\FormController::subscribeAction to adapt and handle the contents of your form submission.

Here is a simple template case for reference only:

<div class="register-form">
    <div class="input-group">
        <div class="register-form-email-label">
            <label for="form_email">Email Address</label>
        </div>
        <input type="email" id="form_email" name="email" required="required" autocomplete="off">
        <button type="submit" id="form_save" name="save" class="register-form-button">Register</button>
    </div>
</div>

Next, in the subscribeAction function, we set up a route /newsletter/register to handle the form submission.
For example, if the form is submitted via AJAX with a POST method, we can send the user's inputted email address from the template to the subscribeAction function to process the subscription to the newsletter.

Here is a code snippet of an AJAX example for reference:

$.ajax(
{
    url: '/newsletter/register',
    type: 'POST',
    data: {template: '@ibexadesign/xxx/registerform.html.twig'},
    beforeSend: function () {
        Do something...
    },
    success: function (result) {
        Do something...
    },
    error: function () {
        Do something...
    }
})

It is important to note that if we are using a new API to handle the newsletter functionality, the logic in the subscribeAction function may need to be adjusted accordingly. This may require rewriting the function to meet the specific requirements of the API.

1) Add API key

First, make sure to properly configure the reCAPTCHA API Key in your configuration file (newsletter.yaml) by setting the recaptcha_sitekey and recaptcha_secretkey fields.

For example:

xrow_newsletter:
    recaptcha_sitekey: sitekey-123
    recaptcha_secretkey: secretkey-456

2) Implement HTML code

Next, add the reCAPTCHA component in the HTML code of your own developed "registration form"-template file.

<div class="g-recaptcha" data-sitekey="{{ captcha_site_key }}"></div>

3) Configure validation

The isValidCaptcha function in Xrow\NewsletterBundle\Controller\FormController will validate reCAPTCHA. If the validation is successful, it will continue to process the form submission. If it fails, it will return an error message.

Testing newsletters with Maileon¶

When Maileon tries to generate a newsletter, it copies all images referenced by the newsletter to its own server (for example https://images.maileon-static.com/c/IQj9-yPhPxMaKzmrM4MUfg).
So if your website is on a local machine or behind a firewall where the Maileon servers cannot reach it, it will not be able to fetch the images. To fully test newsletter generation end-to-end, make sure that your website is publicly available.

Last update: February 13, 2023

Developers Guide¶

Introduction¶

Supporting a New Newsletter API¶

How to create a Newsletter Subscription Form¶

How to use reCAPTCHA in a newsletter subscription form¶

Testing newsletters with Maileon¶