Inhalt dieser Anleitung

Dieser Beitrag beschreibt, wie man die Inhalte der Benachrichtigungsmails beim Hochladen von Dokumenten in die Joomla-Erweiterung ProjektFork ändern kann. Das Beispiel bezieht sich also konkret auf den Dokumente-Upload, kann aber adäquat auch für die anderen Benachrichtigungsmails von ProjektFork angewendet werden.

Die Beschreibung bezieht sich auf ProjectFork 4, trifft aber ähnlich zu für Vorgänger und Nachfolgeversionen.

In einem konkreten Kundenprojekt bestand die Aufgabenstellung darin diverse Änderungen in den Benachrichtigungsmails vorzunehmen. Natürlich bin ich diesem Fall immer bemüht, diese notwendigen Modifikationen nicht in Core-Scripte der Komponten durchzuführen, sondern idealerweise durch sauberes Overriding, so wie im Joomla-Framework als Konzept vorgesehen. Leider muss man für ProjectFork feststellen, dass es für diese Benachrichtigungsmails keine wirklichen, dedizierten Mailtemplatescripte gibt. Erst recht gibt es keine Administrationsmöglichkeiten über das Backend. Das macht die Sache also kompliziert. 

Leider sind die Anleitungen für ProjektFork nicht sonderlich umfangreich für die Lösungen solcher Aufgabenstellungen, weshalb ich mir diese Lösungen selbst erarbeitet habe und mein KnowHow der Gemeinschaft hier bereitstellen will. Hier wird also auch etwas Hintergrundwissen über ProjectFork angeboten, etwas darüber wie die relevanten Scriptstrukturen aufgebaut sind.

Wenn Ihnen dieser Beitrag gefällt, freue ich mich auf Ihr Feedback. Nutzen Sie die Kommentarfunktion für ergänzende Erfahrungen. Bitte beachten Sie, dass dies hier keine Forum ist und ich auch keinen unentgeltlichen Support leisten kann. Unter Anerkennung dieser Tatsache, können Sie mich bei Fragen gern kontaktieren. Bitte beachten Sie auch die Werbeschaltungen auf dieser Seite, damit wird meine Mühe etwas refinanziert.

Grundwissen zu ProjectFork

Das zentrale Benachrichtigungs-Plugin (PF Notifications)

Ein Besonderheit ist, dass ProjectFork für den Versendung aller Benachrichtigungen ein zentral genutztes Mail-Plugin mitbringt. Dieses ist zu finden im System-Pluginpfad unter plugins/content/pfnotifications. Eines der wichtigsten Gründe, warum das von PF so praktiziert wurde, ist dass es für die Mailbenachrichtigung u.a. die Möglichkeit gibt, diese per CronJob oder Joomla-Systemereignisse zu triggern. Deshalb wird hier also zentral ein System-Plugin eingebunden, welches diese Maßnahmen konfigurationsabhängig ausführt.

Die Benachrichtigungsscripte der einzelen PF-Komponenten

Weiterhin ist es ungewöhnlich für Joomla-Erweiterungen, dass eine einzelne Anwendung hierfür mehrere Komponenten intstalliert. PF teilt seine unterschiedlichen Aufgabenbereiche in je einzelne dafür verantwortlichen Komponenten, was sich dann natürlich auch auf die Pfadstrukturen auswirkt. Z.B. im Verzeichnis administrator/components befinden sich nach der Installation dann diverse Unterordner die mit com_pf beginnen, wie z.B. com_pfmilestones, com_pfrepo etc.

In den "Unter"-Komponenten von PF, welche Benachrichtigungen verschicken, gibt es in dem Unterordner helpers dann jeweils ein Script notifications.php, welches mit o.g. Plugin arbeitet und die komponentenabhängigen Inhalte für die Benachrichtigungen einsteuert.

Die Sprachdateien und -konstanten für die Mailinhalte

Ein dritter wesentlicher Baustein bei der Erzeugung der Mails, ist die Ergänzung durch Sprachdatei. Getreu dem Joomla-Prinzip, Textausgaben in INI-Dateien sprachabhängig zu verwalten, verfährt auch PF auf gleiche Weise. Das ist von großem Vorteil für die o.g. Aufgabenstellung, denn hier funktioniert das Joomla-Sprach-Override, so dass einige Inhaltsänderungen damit schon elegant erreicht werden können 1. ohne Core-Scripte anfassen zu müssen, und 2. dies schon über das J!Backend gänzlich ohne eine einzig Datei ändern zu müssen.

Umsetzung im Detail

Einfache Textänderungen - Wortlaut

Wie boen beschrieben nutzt PF Sprachdateien. Die Sprachkonstanten können im Backend wie unter Joomla üblich überschrieben werden (Adminbereich > Erweiterungen > Sprachen > Overrides > Filter: gewünschte Site-Sprache auswählen, dann den Dialog nutzen um die Sprachkonstanen zu überschreiben). Welche Sprachkonstanten Sie verwenden müssen, findet man heraus in dem man nach den aktuell verwendeten Sprachphrasen in den INI-Dateien sucht. z.B. werden für Dateibenachrichtigungen in den Mails die drei Sprachkonstanten COM_PFREPO_FILE_EMAIL_NEW_MESSAGE, COM_PFREPO_FILE_EMAIL_UPD_MESSAGE und COM_PROJECTFORK_EMAIL_FOOTER verwendet. 

Wenn man sich nun die Inhalte dieser Konstanten anschaut, wird man feststellen, dass diese sprintf-Platzhalter (Argumente) verwenden - in der Syntax %s. In diese Platzhalter werden die variablen, projekt- bzw. dateiabhängigen Inhalte eingesetzt. In begrenztem Umfang können wir diese auch ändern. Dazu ist wichtig, dass man den php-Befehl sprintf() kennt und versteht. Wer jetzt z.B. die Reihenfolge dieser Argumente im Text verändern will, kann das nur unter Verwendung der %X$s - Syntax machen für X müssen Sie die Reihenfolgenummer eingeben, wie im Befehlsaufruf von sprintf in der jeweiligen PF-Methode übergeben. So ist es dann möglich Argument 4 vor 3 ausgeben zu lassen oder gar Argumente wegzulassen.

Hier ein beispiel für ein modifizierten Mailfooter:

Bei Fragen können Sie sich telefonisch oder per E-Mail unter Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein. an uns wenden.\n\nDiese E-Mail wurde automatisch erstellt. Eine Antwort wird vom System nicht verarbeitet.\n\nMit freundlichen Grüßen\n\nIhr Support-Team

Erweitere Inhaltsänderungen - Variablen-Inhalte 

Kompliziert wird es dann, wenn man Daten ausgeben will, die in der PF-Methode als sprintf-Argumente nicht vorgesehen sind, denn dann muss man diese erst bereitstellen. Das beschreiben wir nun. Wärend bisher alles ohne Scipten ablief, wird nun leider eine Core-Script-Modifikation notwendig. 

Wir wollen zum Bsp. erreichen, dass der Dateiname der hochgeladenen Datei nicht nur in der Betreffzeile (subject) steht, sondern auch im Text genannt wird. Da wir nun am Beispiel der Dateiaktionen-Benachrichtigung demonstrieren wollen, ist für uns das Benachrichtigungsscript administrator/components/com_pfrepo/helpers/notifications.php relevant. Hier gibt es zwei Methoden: getNoteSubject() erzeugt die Betreffzeile. In dieser können wir erfahren in welchem Parameter der Dateiname übergeben wird. Die Methode getFileMessage() ist für die Ausgabe des Mail-Inhaltes verantwortlich. Die Zeile 

$txt = sprintf($format, $receiver->name, $user->name, $changes, $link);

ergänzen wir durch $after->title wir folgt:

$txt = sprintf($format, $receiver->name, $user->name, $changes, $link, $after->title);

Damit wird ein 6. Parameter an sprintf übergeben. Der 3. Parameter wird gar nicht verwendet. Unser Mail-Text wird nun über das Sprach-Override der Konstant COM_PFREPO_FILE_EMAIL_NEW_MESSAGE mit folgendem Inhalt belegt:

Hallo Herr/Frau %1$s,\n\n%2$s hat folgende Datei in Ihrem persönlichen Kundenbereich für Sie hochgeladen: %5$s \n\nBitte stellen Sie vorab sicher, dass Sie unter http://www.domain.de/ angemeldet sind. Sollte dies nicht der Fall sein, öffnen Sie bitte unsere Internetseite und melden Sie sich mit Ihren Zugangsdaten an.\n\nZum Herunterladen auf den unten stehenden Link klicken:\n\n%4$s

Wir sehen hier die numerierten Argumente in anderer Reihenfolge als an sprintf übergeben und das neue Argument in %5$s womit unser Dateiname ausgeben wird.