Administrator-Handbuch

Man braucht nicht unbedingt die Extension tt_address und mail, um diese Extension benutzen zu können. Es geht auch ohne, aber mehr Sinn macht es schon, wenn man die Tabellen tt_address oder fe_users benutzt. Die Tabelle fe_users kann man zusammen mit der Extension Luxletter oder Mail benutzen. Benutzer können sich dann zum Newsletter anmelden, wenn die Tabelle tt_address oder fe_users in der Newsletter-Extension benutzt wird.

Templates

Man findet 2 Ordner mit Templates: Email und Log. Im Log-Ordner findet man die Templates für die Formulare. Wenn ein Benutzer solch ein Formular absendet, landen die Daten in der Tabelle tx_fpnewsletter_domain_model_log. Erst nachdem ein Benutzer seine E-Mail-Adresse verifiziert hat, werden die Daten in die Tabelle tt_address oder fe_users kopiert.

Im Email-Ordner findet man die Templates, die per E-Mail verschickt werden. Es gibt Email-Templates für die Verifizierung der E-Mail-Adresse und für den Admin. UserToAdmin wird vor der Verifikation benutzt und SubscribeToAdmin nach der Verifikation der E-Mail-Adresse. Zum ändern der Templates muss man sie z.B. nach fileadmin kopieren und den Link dazu angeben:

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

Es gibt eine Text- und eine HTML-Version für die E-Mails. Und es gibt beide Templates auch in deutsch und in englisch (außer die für den Admin). Standardmässig musste man bis Version 3.0.0 für jede Sprache neue Templates anlegen. Das Default-Template enthält übersetzbare Texte ab Version 3.0.0 und bis Version 3.0.0 sind Template ohne Zahlen-Endung in deutsch verfasst und z.B. SubscribeVerify1.html in englisch verfasst. Ab Version 3.0.0 haben die deutschen Templates die Endung 0.html. Es werden automatisch diese Templates verwendet, wenn settings.email.dontAppendL=0 ist:

SubscribeVerify<LANGUID>.html and SubscribeVerify<LANGUID>.txt

Für die Sprache 0 muss man die Zahl weglassen bis Version 3.0.0. SubscribeVerify1.txt ist das Template für die Sprache 1.

Man kann dieses Verhalten jedoch mit der Einstellung email.dontAppendL=1 abschalten! In dem Fall kann man die Variable {sys_language_uid} in den E-Mail-Templates verwenden. Man kann also mit Hilfe von <f:if condition="{sys_language_uid} == 1"> mehrere Sprachen in einem Template verwenden.

Man kann folgende keys in den E-Mail-Templates benutzen: 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 und email.first-name.

Beachte

Standardmässig wird neben der E-Mail-Adresse auch Anrede und Name in den E-Mails verwendet. Es wird empfohlen, diese zu highlighten, um Spam/Pishing-Emails vorzubeugen.

Wichtig

Seit Version 5.x wird nicht nur ein Plugin-Name verwendet. In manchen Fällen muss man deshalb leider die Templates anpassen und entweder den pi-Parameter hinzufügen oder entfernen! Beispielsweise bei der Abmeldeseite ohne Verifizierung-Seite.

Anmeldeformular auf jeder Seite

Du willst ein Anmeldeformular in dein Seiten-Template einbauen? Z.B. auf jeder Seite in den Footer? Da gibt es 2 Möglichkeiten.

Erste Möglichkeit: füge ein statisches Formular in dein Footer-Template ein. Diese Extension kann die Parameter aus diesem Formular auslesen. Lies das Kapitel "Konfiguration -> Externe Felder" für mehr Details dazu.

Zweite Möglichkeit: du kannst ein Plugin via f:cObject typoscriptObjectPath in dein Template einbauen. Beispiel:

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

Dafür musst du lib.nlsubscriptionContent in deinem TypoScript-Template wie folgt definieren:

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

Ersetze 0 und 22 durch die colPos und page-uid, welche du benutzt hast auf der Seite mit dem Anmelde-Plugin. Falls du das Anmelde-Plugin von fp_newsletter benutzt, solltest du das cachable Anmelde-Formular dort auswählen. In dem Fall muss noch eine Seite für die Anmeldung definiert werden, wohin das Formular umleiten soll. Ein mathematisches Captcha ist bei diesem cachable Anmelde-Formular nicht möglich!

Anmerkung für die Mail-Extension

Wenn man die Mail-Extension benutzt, kann man die Tabellen tt_address oder fe_users benutzen. Wenn man tt_address benutzt, werden diese zusätzlichen Felder befüllt: mail_html, mail_salutation und mail_active. Wenn man fe_users benutzt, werden diese zusätzlichen Felder befüllt: mail_html, mail_salutation, mail_active und categories von categoryOrGroup. Es wird keine Gruppe zugewiesen!

Anmerkung für die Luxletter-Extension

Wenn man die Luxletter-Extension benutzt, kann man nur die Tabelle fe_users verwenden. Diese zusätzlichen Felder werden befüllt: Gruppe von categoryOrGroup und wenn die Setting newsletterExtension=luxletter gesetzt ist: luxletter_language.

Abmelden via Mail-Extension

Wenn du einen Newsletter verschickst, soll darin sicherlich auch ein Abmeldelink drin stehen. Das kann man so machen, wenn man mail benutzt:

Newsletter abbestellen:
https://www.domain.de/newsletter/abmelden.html?email=###USER_email###&authcode=###MAIL_AUTHCODE###

Ersetze den Link durch deine Abmeldeseite und füge ihn in dein Newsletter-Template oder den Newsletter-Inhalt ein. ###USER_email### und ###MAIL_AUTHCODE### wird von mail automatisch ersetzt. Der email- und authCodeFields-Parameter kann so geändert werden via TypoScript:

plugin.tx_fpnewsletter.settings.parameters.email = email
plugin.tx_fpnewsletter.settings.parameters.authcode = authcode

Die Extension fp_newsletter wird die Parameter lesen und die E-Mail als Default-E-Mail-Adresse setzen oder den Abonnenten gleich abmelden. Achtung: bei der Zielseite muss dabei das Plugin "Newsletter: Abmeldung via Formular" oder "Newsletter: Abmeldung via mail-Link" ausgewählt sein. In letzterem Fall muss auch settings.authCodeFields gesetzt werden. Nachteil: man kann sich mit fp_newsletter nicht nur von einem speziellen Newsletter abmelden. Man wird von allen abonnierten Newslettern eines Ordners abgemeldet.

Abmelden via Luxletter-Extension

Luxletter bietet auch einen Abmeldelink an. Zusätzlich bietet Luxletter ein Plugin, mit dem man sich aus dem Newsletter austragen kann. Wenn man das Plugin benutzt, wird kein Log-Eintrag von fp_newsletter geändert. Der Status ändert sich also nicht. Zudem wird nur die fe_groups Kategorie beim Abonnenten gelöscht.

Einen ganz anderen Weg beschreitet fp_newsletter, wenn man auf der Zielseite "Newsletter: Abmeldung via luxletter-Link" benutzt. In diesem Fall wird der Log-Eintrag aktuell gehalten und weiterhin wird nicht nur eine Kategorie beim Abonnenten entfernt, sondern der ganze fe_users-Eintrag wird gleich gelöscht. Nachteil: man kann sich mit fp_newsletter nicht nur von einem speziellen Newsletter abmelden. Man wird von allen abonnierten Newslettern eines Ordners abgemeldet.

Beispiel für einen Abmelde-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;">
  Newsletter abbestellen
</f:link.external>

Setze plugin.tx_fpnewsletter.settings.unsubscribeMode = 1 wenn stattdessen erst das Abmeldeformular gezeigt werden soll.

Captchas

Man kann 3 verschiedene Captcha-Methoden benutzen. 2 davon kann man via TypoScript-Einstellungen konfigurieren. Siehe Kapitel "Configuration". Die 3. Methode ist eine spezielle Lösung, die PHP-Kenntnisse voraussetzt, weil man noch 1-2 weitere Extensions dafür benötigt.

Diese Extension stellt ein Validate-Event zur Verfügung, welches im New.html Template dieser Extension wie folgt benutzt werden kann:

<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>

Füge xmlns:fp="https://typo3.org/ns/YourVendor/YourExtension/ViewHelpers" hinzu und ersetzte YourVendor und YourExtension.
Füge <fp:form.friendlyCaptcha name="captcha_solution">...</fp:form.friendlyCaptcha>
hinzu und passe es an deine Extension an. Füge die TypoScript settings "site_key" hinzu.
Bemerkung: diese Zeilen zeigen nur ein Beispiel für eine "friendly captcha" Lösung.

Weiterhin braucht man einen Event-Listener in der eigenen Captcha-Extension. Er sollte so in etwa aussehen::

  use YourVendor\YourExtension\Services\CaptchaService;
  use Fixpunkt\FpNewsletter\Events\ValidateEvent;
  use TYPO3\CMS\Extbase\Utility\DebuggerUtility;
  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");
          }
      }
  }

Weitere Felder zu tt_address hinzufügen

Wenn du weitere Felder zu tt_address hinzufügen möchtest, dann müssen diese Felder sowohl in der Log-Tabelle (tx_fpnewsletter_domain_model_log) als auch in der tt_address-Tabelle vorhanden sein. Wenn sie noch nicht da sind, müssen sie in einer Extension in der Datei ext_tables.sql hinzugefügt werden. Beispiel: du willst das Feld "gdpr" nach tt_address kopieren. Dieses Feld ist in der Log-Tabelle bereits vorhanden und deshalb muss es nur noch zur tt_address-Tabelle von dir hinzugefügt werden. Danach muss man noch per TypoScript angeben, welche zusätzlichen Felder mit kopiert werden soll:

plugin.tx_fpnewsletter.settings.additionalTtAddressFields = gdpr

Das ist alles.

Sicherheitshinweis zu Version 3.2.6

Falls du eine ältere Version benutzt, solltest du folgendes über die behobenen Fixes wissen:

  1. Man konnte bisher alle Newsletter-Empfänger abmelden.

  2. Der TypoScript-Wert für plugin.tx_fpnewsletter.settings.doubleOptOut wurde auf 1 gesetzt.

Du könntest diesen Wert auch auf 1 setzen, falls nichts gegen double-opt-out bei der Abmeldung spricht.

  1. Es war möglich, beim mathematischen Captcha-Check zu mogeln.

  2. Es war möglich, Daten über andere Newsletter-Empfänger bei der An- oder Abmeldung zu erfahren.

Deshalb sollte man unbedingt updaten!

Updaten auf Version 6.x

Weil der Support für die Extension direct_mail in Version 6.0.0 entfernt wurde, wurden auch manche TypoScript-Variablen umbenannt! Leider gibt es nur ein Update-Skript, welches die alten Variablen in FlexForms umbenennt. Du musst nun also selber im TypoScript-Setup und in HTML-Templates Anpassungen vornehmen. Das heißt, du musst gesetzte TypoScript-Variablen selber umbenennen und in eigenen HTML-Dateien (FormFields.html und FormFieldsEdit.html) Felder umbenennen. Betroffen sind diese 3 TypoScript-Settings:

  1. "dmUnsubscribeMode" wurde umbenannt zu "unsubscribeMode".

  2. "module_sys_dmail_html" wurde umbenannt zu "html".

  3. "module_sys_dmail_category" wurde umbenannt zu "categoryOrGroup".

FAQ

  • Es läuft nicht richtig. Was kann ich tun?

    Möglicherweise muss man die storagePID doppelt angeben: via Plugin und via TypoScript. Beachte, dass man für die Abmeldung eine eigene Seite braucht!

  • Ein Link funktioniert nicht so wie er sollte. Was ist falsch?

    Seit Version 5.x gibt es mehr als nur ein Plugin (pi1). Vielleicht ist ein falsches Plugin im Link? Siehe Kapitel "Wichtig" weiter oben.

  • Die Domain fehlt im Link in der E-Mail. Wieso?

    TYPO3 9 ignoriert anscheinend den Parameter absolute="1"? Oder du hast keine Domain im Backend angegeben? Füge die Domain dann selber hinzu.

  • Was ist der username wenn ich die Tabelle fe_users verwende?

    Als username wird die E-Mail-Adresse verwendet. Das Standard-Passwort ist joh316. Die Gruppe setzt man mittels categoryOrGroup.

  • Ich benutzte die fe_users Tabelle, aber es passiert nichts.

    Hast du auch settings.categoryOrGroup gesetzt?

  • Ich benutzte die tt_address Tabelle, aber nicht die mail-Extension und es passiert nichts.

    Hast du auch settings.html=-1 gesetzt? Für das HTML-Feld wird nämlich direct_mail/mail benötigt.

  • Ich brauche / will keine Log-Einträge. Kann man das ausschalten?

    Nicht ganz. Man kann nur alte Log-Einträge automatisch löschen lassen. Dazu fügt man einen Task "Tabellen-Müllsammlung" hinzu und wählt da die Tabelle tx_fpnewsletter_domain_model_log aus. Dann kann man angeben, nach wie vielen Tagen ein Log-Eintrag gelöscht werden soll. Wenn der ConJob läuft, werden alte Log-Einträge dann automatisch gelöscht.