What does it do?

The extension fp_newsletter is designed to provide a newsletter subscription and unsubscription service for the table tt_address or fe_users which can be used by the extension mail or luxletter. Furthermore it is designed to be compatible with the GDPR. A log is written about (every) action in a separate table. Old log entries can be deleted by a scheduler task. Note: there are more TypoScript-settings than FlexForm-settings. But the extension can be used without tt_address/fe_users too. Therefore an admin-email-address can be specified. The admin will then get an email with the subscription data. Google reCaptcha v3 or a mathematical captcha can be enabled too. There is a widget for the dashboard available. Available languages: english, german/deutsch, french/français and italian/italiano. The standard language is german, but english texts are also available.

Screenshots

One example view of a frontend page:

Templates

You will find 4 folders in the Templates-folders: Backend, Widget, Email and Log. Backend and Widget are used only in the backend. In the Log-folder are the form-templates. If a user submits the form, the entries lands in the table tx_fpnewsletter_domain_model_log. Only if a user verifies his email-address, his entry will be copied to the table tt_address.

In the Email-folder you find the templates for the email to use user. Its the email for verifying the email-address. And there are email-templates for the admin: UserToAdmin is sent before verification and SubscribeToAdmin is sent after the email verification. If you want to change the text of the email, copy the templates e.g. to fileadmin and set the new path via TypoScript setup:

plugin.tx_fpnewsletter.view.templateRootPaths.1 = fileadmin/bsdist/theme/tmpl/fp_newsletter/Templates/

There is a text and a HTML version for email-templates. There you can use the variable {sys_language_uid} in the email templates. You could use <f:if condition="{sys_language_uid} == 1"> to use more than one language in one template.

You can use this translate keys in the email templates: email.dear-gender-first-and-last-name, email.dear-first-and-last-name, email.dear-first-name, email.dear, email.gender-first-and-last-name, email.first-and-last-name and email.first-name.

Subscription form on every page

You want to insert a newsletter subscription form to your fluid page template? E.g. in the footer of every page? Then you have 2 possibilities.

First way: insert a static form in your template. This extension can read this variables if you provide the used form elements. Read the chapter "Configuration -> External fields" for more information about this way.

Second way: you can load the plugin via f:cObject typoscriptObjectPath in your page template like this:

<f:cObject typoscriptObjectPath="lib.nlsubscriptionContent" />

Therefore you need to define lib.nlsubscriptionContent like this:

lib.nlsubscriptionContent = CONTENT
lib.nlsubscriptionContent {
  table = tt_content
  wrap = |
  select {
    pidInList = 22
    where = colPos = 0
  }
}

Replace the 0 and 22 with your used colPos and page-uid at the page with your subscription form. If you use the plugin from fp_newsletter for a subscription form, you should select the cacheable subscription form. In this case you must define a page for the subscription too. The form will have that page as target.

Note: you can not use a mathematical captcha on the cacheable subscription form.

Note: you must remove a non-static form on pages that uses the fp_newsletter plugin. E.g. use this on pages that have a verification or delete plugin:

lib.nlsubscriptionContent >
lib.nlsubscriptionContent = TEXT
lib.nlsubscriptionContent.value =

Using other salutations

If you don´t like the salutations in the sent email, you can change the text via TypoScript. See chapter configuration. If you want that it depends on the gender you need to change the Partials/Email/Salutation.html file. Example:

<f:if condition="{gender_id}==1 && {lastname}">
  <f:then>
    <f:translate key="email.dear-mrs-last-name" arguments="{0: lastname}" extensionName="FpNewsletter" languageKey="{language_code}" />
  </f:then>
</f:if>
<f:if condition="{gender_id}==2 && {lastname}">
  <f:then>
    <f:translate key="email.dear-mr-last-name" arguments="{0: lastname}" extensionName="FpNewsletter" languageKey="{language_code}" />
  </f:then>
</f:if>

You can now use new TypoScript settings. TypoScript example for the above partial:

plugin.tx_fpnewsletter._LOCAL_LANG.de.email.dear-mr-last-name = Sehr geehrter Herr %s,
plugin.tx_fpnewsletter._LOCAL_LANG.de.email.dear-mrs-last-name = Sehr geehrte Frau %s,

Using own categories/groups

From version 8.2.0 you can use own categories or groups in your templates. First set the setting settings.categoryOrGroup to e.g. 1 at the subscription page:

plugin.tx_fpnewsletter.settings.categoryOrGroup = 1

Second set the setting settings.categoryOrGroup to "" (empty value) at the verify page:

plugin.tx_fpnewsletter.settings.categoryOrGroup =

Third add a list of categories or groups in the Partials/Log/FormFields.html Therefore replace this line:

<f:form.hidden property="categories" value="{settings.categoryOrGroup}" id="fp_categories" />

with something like this:

<div class="form-group">
  <label class="form-label" class="form-label">Choose a group:</label>
  <div class="form-check">
      <label for="fp_category_1" class="form-check-label">
          <f:form.radio class="form-check-input radiobox categories" id="fp_category_1" property="categories" value="3" /> Greenhorn
      </label>
  </div>
  <div class="form-check">
      <label for="fp_category_2" class="form-check-label">
          <f:form.radio class="form-check-input radiobox categories" id="fp_category_2" property="categories" value="4" /> Customer
      </label>
  </div>
  <div class="form-check">
      <label for="fp_category_3" class="form-check-label">
          <f:form.radio class="form-check-input radiobox categories" id="fp_category_3" property="categories" value="5" /> Employee
      </label>
  </div>
</div>

Now the saved value will be used instead of the value of settings.categoryOrGroup.

Note: on the unsubscribe page, settings.categoryOrGroup needs to be set too to e.g. 1.

Note: this was not tested with the edit form.

Note for the Mail-extension

If you are using the Mail-Extension, you can use tt_address or fe_users. If you are using tt_address, this additional fields will be filled: mail_html, mail_salutation and mail_active. If you use the table fe_users, this additional fields will be set: mail_html, mail_salutation, mail_active and categories from categoryOrGroup. New users will not have a group set!

Note for the Luxletter-extension

If you are using the Luxletter-Extension, you can use only the table fe_users. This additional fields will be filled: user group with categoryOrGroup and if the setting newsletterExtension=luxletter is set: luxletter_language.

Unsubscription via Mail-extension

When you send a newsletter you want to add an unsubscription link to your newsletter. If you are using mail, you can do that this way:

Unsubscribe from the newsletter:
https://www.domain.com/newsletter/unsubscribe.html?email=###USER_email###&authcode=###MAIL_AUTHCODE###

Replace the link with the link to your unsubscribe page and put it in the newsletter-template or use it as email-content. ###USER_email### and ###MAIL_AUTHCODE### will be replaced by the mail-extension. The parameters can be changed. It must be set via TypoScript:

plugin.tx_fpnewsletter.settings.parameters.email = email
plugin.tx_fpnewsletter.settings.parameters.authcode = authcode
plugin.tx_fpnewsletter.settings.authCodeFields = gender,name

The extension fp_newsletter will read those parameters and use the email as default email-address or it will make a direct unsubscription. Note: copy "Fields ... of authentication codes" from mail to plugin.tx_fpnewsletter.settings.authCodeFields too. Note: at the target page you need to select the plugin "Newsletter: unsubscribe via form" or "Newsletter: unsubscribe via mail-link" from this extension. In the last case, settings.authCodeFields must be set too. Disadvantage: it is not possible to unsubscribe only from a specific newsletter in a folder. The whole tt_address entry will be deleted! Note: this method does not work with test-newsletters!!!

Unsubscription via Luxletter-extension

There is a unsubscribe link in the luxletter template. If you use the Luxletter-plugin at the target page, it is not possible to change the status of a Log entry. Furthermore Luxletter removes only the fe_groups category of a fe_users entry. The user remains present.

An completely other ways uses fp_newsletter, if you use "Newsletter: unsubscribe via luxletter-link" of fp_newsletter. In this case, a fp_newsletter log is created and the subscriber will be removed from fe_users. Disadvantage: it is not possible to unsubscribe only from a specific newsletter in a folder. The whole fe_users entry will be deleted!

Example for an unsubscribe-link:

<f:link.external uri="{luxletter:mail.getUnsubscribeUrl(newsletter:newsletter,user:user,site:site)}" additionalAttributes="{data-luxletter-parselink:'false'}" target="_blank" style="font-family:'FiraSans-Light', 'Helvetica Neue', Arial, sans-serif;">
  Unsubscribe from this newsletter abbestellen
</f:link.external>

Set plugin.tx_fpnewsletter.settings.unsubscribeMode = 1 if the unsubscription form should be shown instead of the direct unsubscription.

Captchas

You can use 3 different captchas. 2 of them can be configured via TypoScript settings. See chapter "Configuration". The third method is a custom captcha validator and requires PHP acknowledgment, because you will need a second extension. And maybe a third one, e.g. a "friendly captcha" extension.

This extension provides a validate event. If you want to use this validator, add some lines to the New.html template of this extension:

 <html xmlns:fp="https://typo3.org/ns/YourVendor/YourExtension/ViewHelpers" xmlns:f="https://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers" data-namespace-typo3-fluid="true">
   ...
   <f:form action="create" name="log" pluginName="new" object="{log}">
	<f:render partial="Log/FormFields" arguments="{_all}" />
	<fp:form.friendlyCaptcha name="captcha_solution">
		<div class="frc-captcha" data-sitekey="{settings.site_key}" data-solution-field-name="{name}" data-start="focus"></div>
	</fp:form.friendlyCaptcha>
	<div class="text-right">
		<f:form.submit value="{f:translate(key: 'subscribe', default: 'subscribe')}" class="btn btn-primary" />
	</div>
</f:form>
   ...
 </html>

 Add xmlns:fp="https://typo3.org/ns/YourVendor/YourExtension/ViewHelpers" and replace YourVendor and YourExtension.
 Add <fp:form.friendlyCaptcha name="captcha_solution">...</fp:form.friendlyCaptcha>
 and adapt it to your custom captcha extension. And set the TypoScript settings "site_key".
 Note: the lines about shows you only an example for a "friendly captcha" solution.

 Furthermore you need an event listener in your custom captcha extension. It may look like this::

   use YourVendor\YourExtension\Services\CaptchaService;
   use Fixpunkt\FpNewsletter\Events\ValidateEvent;
   use Psr\Http\Message\ServerRequestInterface;

   class NewsletterValidationListener
   {

       /** @var CaptchaService  */
       protected CaptchaService $captchaService;

       /**
        * @param CaptchaService $captchaService
        */
       public function __construct(CaptchaService $captchaService) {
           $this -> captchaService = $captchaService;
       }

       /**
        * Checks if the captcha was solved correctly.
        * @param ValidateEvent $event
        * @return void
        */
       public function __invoke(ValidateEvent $event) : void {
           /** @var ServerRequestInterface $request */
           $request = $GLOBALS['TYPO3_REQUEST'];

           $pluginName = "tx_fpnewsletter_pi1";

           // see if data was provided
           if(!key_exists($pluginName, $request -> getParsedBody()) || !is_array($request -> getParsedBody()[$pluginName])) {
               $event -> setValid(false);
               return;
           }

           [...]

           // validate solution
           $solution = $request -> getParsedBody()[$pluginName]["captcha_solution"];
           $valid = $this -> captchaService -> validate($solution);
           if(!$valid["verified"]) {
               $event -> setValid(false);
               $event -> setMessage("Captcha not valid");
           }
       }
   }

Adding additional fields to tt_address

If you want to add additional fields to tt_address, they must be already present in the log-table (tx_fpnewsletter_domain_model_log) and in the tt_address-table. If they are not present, then you must add the fields to both tables via an own extension in your ext_tables.sql file. Example: you want to add the field "gdpr" to tt_address. This field is already part of the log-table. You need to add it only to the tt_address-table by your own. Then you must specify which additional fields should be copied from the log-table to the tt_address-table via TypoScript:

plugin.tx_fpnewsletter.settings.additionalTtAddressFields = gdpr

That's all.

Security-notice to version 3.2.6

If you use older versions, you should know this information about the fixed security issues:

1. It was possible to unsubscribe all users.
2. The TypoScript value for plugin.tx_fpnewsletter.settings.doubleOptOut was set to 1 by default. You can set it to 1 too if you want to enable double opt out for the unsubscription.
3. It was possible to cheat at the mathematical captcha check.
4. It was possible to get user data at the new- and unsubscribe-action.

Therefore you should update the extension!

Updating to version 6.x

Because the support for the extension direct_mail was removed in version 6.0.0, some TypoScript settings changed the name. Unfortunately there is only a update-script for migrating this fields to the new name for FlexForms. You must adapt your TypoScript settings and HTML-Templates by your own. That means you need to edit your TypoScript-settings and HTML-files (FormFields.html and FormFieldsEdit.html): rename the old names. This settings are affected:

1. dmUnsubscribeMode was renamed to unsubscribeMode.
2. module_sys_dmail_html was renamed to html.
3. module_sys_dmail_category was renamed to categoryOrGroup.

FAQ

• It does not work correct. What can I do?

  Maybe you need to set the storage PID twice: via plugin and via TypoScript. Note, that you need an own page for the newsletter unsubscription.

• A link is not working as expected. Whats wrong?

  Since version 5.x there is more than one plugin. Maybe the plugin is not the right one. See chapter "Important" above.

• The domain is missing in the email. Why?

  TYPO3 9 ignores the parameter absolute="1"? Or you have not added a domain in the backend? Add the domain by your own in that case.

• What will be the username if I use fe_users?

  The username will be the email-address. The default password is joh316. The category can be set via categoryOrGroup and is mandatory!!!

• I use fe_users but nothing happens.

  Have you set the setting categoryOrGroup? You must define a category.

• I use tt_address but not mail and nothing happens.

  Have you set the setting html to -1? For the HTML-option-field direct_mail/mail is required.

• I get the error 'The action "xyz" is not allowed by this plugin.' Whats wrong?

  Maybe you have 2 fp_newsletter plugins on one page. That don´t work. You find a solution for "Subscription form on every page" further up.

• I don´t want/need a log entry. Can I avoid that?

  Not at all. You can add a task to your scheduler: select the task Scheduler / Table garbage collection. Select there the table tx_fpnewsletter_domain_model_log and set the days after the entries should be deleted. If the CronJob is running, the task will delete all old log entries.

Properties for settings

Note*: only a check via browser is made for the optional required fields.

Note**: you need an own page for the unsubscription/edit! unsubscribeUid/editUid should be defined therefore.

Note***: this page is used too, if doubleOptOut=0. unsubscribeMessageUid is not used if doubleOptOut=0.

Note°: this works only at the unsubscription.

Note°°: comma separated list. E.g. 1,3. Without space. Required for external extensions!

Note°°°: the default value was changed from 0 to 1 in version 3.0.0 and even when L=0 0 will be added from version 3.0.0 to the email-templates when email.dontAppendL=0.

Languages

You can overwrite the text for other languages like this (if preferXlfFile=0, else see last line):

[siteLanguage("languageId") == "1"]
plugin.tx_fpnewsletter.settings.company = Your company
plugin.tx_fpnewsletter.settings.gender.please = Please select your gender
plugin.tx_fpnewsletter.settings.gender.mr = Mr.
plugin.tx_fpnewsletter.settings.gender.mrs = Mrs.
plugin.tx_fpnewsletter.settings.email.senderMail = example@test.com
plugin.tx_fpnewsletter.settings.email.senderName = Sender-name
plugin.tx_fpnewsletter.settings.email.subscribeVerifySubject = Please verify your email
plugin.tx_fpnewsletter.settings.email.unsubscribeVerifySubject = Please verify your email
plugin.tx_fpnewsletter.settings.email.adminSubscribeSubject = New newsletter-subscription
plugin.tx_fpnewsletter.settings.email.adminUnsubscribeSubject = New newsletter-unsubscription
plugin.tx_fpnewsletter.settings.email.subscribedSubject = Newsletter-subscription confirmation
plugin.tx_fpnewsletter.settings.email.unsubscribedSubject = Newsletter-unsubscription confirmation
[END]
plugin.tx_fpnewsletter._LOCAL_LANG.default.email.pleaseVerify = Please verify your email-address by clicking here:

Note: if you want to overwrite the text for the default language, remove this lines: [siteLanguage("languageId") == "1"] and [END].

If you enable the setting preferXlfFile, then you can overwrite the text (subject and salutation) like this:

plugin.tx_fpnewsletter._LOCAL_LANG.en.email.subscribedSubject = Your newsletter subscription is now confirmed
plugin.tx_fpnewsletter._LOCAL_LANG.de.email.subscribedSubject = Deine Newsletter-Anmeldung ist nun bestätigt

Note: the default language of the email-templates is german if settings.email.dontAppendL=0! You find the english version in the files that end with 1.html. You should copy the files and modify the path to the templates via TypoScript. See chapter "Administrator manual". Otherwise set settings.email.dontAppendL=1. Note: till version 3.0.0, the default language is german even when settings.email.dontAppendL=1. From version 3.0.0, the email-templates without a appended number are using translated texts by default.

Deprecation-note: dontAppendL will be removed in version 8.0.0. Even all the templates with the ending 0 and 1.

External fields

You can set a default email-address which was submitted before. E.g. you have a form in the footer and the field-name is nlemail, then set the parameter like this:

plugin.tx_fpnewsletter.settings.parameters.email = nlemail

That parameter will be read and the value of that parameter will be used as default email-address.

You can do the subscription via an form in an other extension too. E.g. you have an shop and at the end of the order the user wants to subscribe to the newsletter? Then put this extension under the shop extension an select the action "subscribe via external extension". Furthermore you must specify the POST-parameter, which are used in the other extension like this:

plugin.tx_fpnewsletter.settings.parameters.active = tx_myshop_pi1|newOrder|newsletter
plugin.tx_fpnewsletter.settings.parameters.email = tx_myshop_pi1|newOrder|email

Only parameters of this format are possible. If they are there, a forward will be made to the action create.

Note:

If you have set the setting "[FE][cacheHash][enforceValidation] = 1", then you must add the parameter from above here: "[FE][cacheHash][excludedParameters]".

Captchas

You can use 3 different captcha methods. If you want to use the Google reCaptcha v3 you need to provide the website key and the secret key. If you want to use a mathematical captcha, you can use 1 or 2 digits. The maximum value for 2 digits is 19. Example:

plugin.tx_fpnewsletter.settings.mathCAPTCHA = 2

You can even use an custom captcha like "Friendly Captcha". Read the chapter "Administrator" for more information.

Optional and required fields

Only email and gdpr are mandatory fields in the model. If you need more mandatory fields, you can make them only via TypoScript and the templates required. There are the following optional fields available: gender, title, firstname, lastname, address, zip, city, region, country, phone, mobile, fax, www, position, company. You can make all this fields required. Here an example to enable some of this fields in the subscription form via TypoScript setup:

plugin.tx_fpnewsletter.settings.optionalFields = gender,title,firstname,lastname,www,position,company
plugin.tx_fpnewsletter.settings.optionalFieldsRequired = firstname,lastname,company

Using of categories

The table sys_category contains categories for mail. Use them like this:

plugin.tx_fpnewsletter.settings.categoryOrGroup = 1,3

It will make two entires into sys_category_record_mm and it will set categories in tt_address (after the verification).

The categories are as hidden-field in the template. You could add checkboxes and copy the checked values by jQuery to the hidden-field if you need a more flexible solution.

Note: this setting is used for groups of fe_users too! If you use fe_users, here you can set the fe_groups. That works only with the extension Luxletter. If newsletterExtension=mail is set, user groups are ignored. Therefore only categories are used.

Note: if deleteMode=3 is set, only categories set in categoryOrGroup will be removed. And the flag mail_active will be set to 0, if newsletterExtension=mail is set.

Changing the labels

Like in every extension, you can change the labels and other messages via TypoScript. Here 2 examples:

plugin.tx_fpnewsletter._LOCAL_LANG.de.tx_fpnewsletter_domain_model_log.email = Email
plugin.tx_fpnewsletter._LOCAL_LANG.de.tx_fpnewsletter_domain_model_log.gdpr_desc2 = Ich bin damit einverstanden, dass die von mir angegebenen Daten elektronisch erhoben und gespeichert werden.

You find the designations in the templates used in f:translate key. Note: _LOCAL_LANG.en. does´t work anymore. You need to use .default instead of .en for english text.

Required extensions

This extensions checks in the new action (subscription form) if required extensions are installed. settings.table can be empty, tt_address or fe_users. When it is tt_address, mail is required too, if you use settings.html or settings.categoryOrGroup. You can disable this check:

plugin.tx_fpnewslettersettings.checkForRequiredExtensions = 0

Atention: if you select "other" at "used newsletter extension", then settings.html=-1 will be set, because its not clear, which html-fields other extensions have.

Full working example

Here an full example for luxletter and 2 languages:

plugin.tx_fpnewsletter.view.templateRootPaths.10 = EXT:example/Resources/Private/Ext/fp_newsletter/Templates/
plugin.tx_fpnewsletter.view.partialRootPaths.10 = EXT:example/Resources/Private/Ext/fp_newsletter/Partials/
plugin.tx_fpnewsletter.settings {
    table = fe_users
    optionalFields =
    doubleOptOut = 0
    enableUnsubscribeGdprAsHidden = 1
    honeypot = 1
    preferXlfFile = 1
    gdprUid = 1138
    subscribeUid = 1167
    unsubscribeUid = 1002
    subscribeVerifyUid = 1001
    categoryOrGroup = 19
    company = Ihre Online-Redaktion von „Test“
}
plugin.tx_fpnewsletter._LOCAL_LANG.de {
    subscribe = Absenden
    tx_fpnewsletter_domain_model_log.email = E-Mail-Adresse
    tx_fpnewsletter_domain_model_log.gdpr_desc1 = Ich habe die
    tx_fpnewsletter_domain_model_log.gdpr_link_text = Datenschutzerklärung
    tx_fpnewsletter_domain_model_log.gdpr_desc2 = zur Kenntnis genommen und bin damit einverstanden, dass meine Daten unter Beachtung der gesetzlichen Bestimmungen satzungsgemäß verwendet und automatisiert verarbeitet werden.
    unsubscribe_it = Newsletter abbestellen
    email_send1 = Vielen Dank für Ihr Interesse.<br>Eine Bestätigungs-E-Mail wurde Ihnen zugesandt.
    email_verified = Ihre E-Mail-Adresse wurde erfolgreich aufgenommen.
    email_removed = Sie haben sich erfolgreich von unserem Newsletter abgemeldet.
    email.pleaseVerify = Sie haben sich für unseren Newsletter angemeldet.
    email.pleaseVerify2 = Um die Anmeldung zu bestätigen, klicken Sie bitte auf folgenden Link:
    email.subscribeVerifySubject = Anmeldung zum Newsletter bei www.test.de
}
plugin.tx_fpnewsletter._LOCAL_LANG.default {
    subscribe = Send
    required = required
    tx_fpnewsletter_domain_model_log.email = E-mail address
    tx_fpnewsletter_domain_model_log.gdpr_desc1 = I have noted the
    tx_fpnewsletter_domain_model_log.gdpr_link_text = privacy policy
    tx_fpnewsletter_domain_model_log.gdpr_desc2 = and I agree that my data will be used in accordance with the statutory provisions and processed automatically.
    unsubscribe_it = Unsubscribe newsletter
    email_send1 = Thank you for your interest.<br>A confirmation email has been sent to you.
    email_verified = Your email address has been successfully added.
    email_removed = You have successfully unsubscribed from our newsletter.
    email.pleaseVerify = You've signed up for our newsletter.
    email.pleaseVerify2 = To confirm the registration, please click on the following link:
    email.subscribeVerifySubject = Registration for the newsletter at www.test.com
}
[siteLanguage("languageId") == 1]
    plugin.tx_fpnewsletter.settings.company = Your online editors of “Test”
[END]

As you can see, you can even define own variables and use them. (Example from here: unsubscribe_it.)