Kontaktformular-Tutorial

1. Einleitung

Das vorliegende Tutorial möchte eine weitere Anwendung der Formular-TagLibs und des <core:importdesign />-Tags zeigen. Das hier diskutierte Kontakt-Formular bietet die Möglichkeit, Empänger-Adressen vor Grabbern und Bots zu schützen, die E-Mail-Adressen von Webseiten auslesen. Die Empfängerliste des Formulars ist beliebig konfigurier- und erweiterbar. Die Anwendung kann mit Hilfe des <core:importdesign />-Tags an beliebiger Stelle in eine PageController-basierte Anwendung eingebunden werden.

2. Grundlagen

Auch in diesem Tutorial werden Techniken eingesetzt, die bereits in den vorangegangenen Tutorials zur Anwendung gekommen sind. Der Autor geht davon aus, dass das Kapitel 2 des Kommentarfunktion-Tutorials gelesen und verstanden wurden. Kapitel 2 beschreibt dabei die Trennung der Funktionen einer Software in drei Schichten, denen unterschiedliche Funktionen zugeteilt werden. Weiterhin beschreibt das Kapitel, wie Domain-Objekte zur Kommunikation zwischen den genannten Schichten fungieren und welche Rolle das MVC-Pattern bei der Implementierung einer Anwendung spielt.

2.1. Konfiguration

Um die Applikation in unterschiedlichen Projekten einsetzbar zu machen müssen Projekt-spezifische Belange in Konfigurationsdateien ausgelagert werden. Konfiguration ist beim Kontaktformular in zweierlei Hinsicht notwendig: Zum einen müssen die Enpfänger-Namen und -Adressen konfigurierbar sein, zum anderen müssen die Ausgabetexte der verwendeten Formular-TagLibs (Validatoren) für das Projekt konfiguriert werden.

An dieser Stelle soll ein kleiner Exkurs zur Konfiguration der Formular-Validatoren eingeschoben werden:
Die Tags

• <form:validate />
• <valgroup:validate />

benötigen zur Ausgabe einer Validierungsmeldung eine sprachabhängige Konfigurationsdatei, die die entsprechenden Texte beinhaltet. Die Konfigurationsdatei wird dabei unter dem Pfad erwartet. {CONTEXT} ist dabei der Context der aktuellen Applikation und {ENVIRONMENT} ist gegen den Wert der Umgebungsvariable der Registry zu ersetzen. Im Fall der vorliegenden Dokumentationsseite wird die Datei unter erwartet. Wie im Kapitel Standard TagLibs unter 2.3.16 und 2.3.17 zu lesen ist, können jedem der genannten Tags die optionalen Attribute

• msginputreq=""
• msginputwrg=""

mitgegeben werden. Diese definieren einen Konfigurationsschlüssel, der einen sprachabhängigen Text enthällt, der bei Eingabe eines nicht gültigen Wertes angezeigt wird. Mit diesem Mechanismus werden zwei Bereiche abgedeckt: einerseits ist es möglich, einen Satz an Texten für eine komplette Applikation zu definieren und diese anschließend in mehreren Modulen nutzen zu können, zum anderen werden die Texte in einfache Textedateien ausgelagert und können einfach übersetzt werden.

Beispiel:
Soll bei der Validierung eines E-Mail-Feldes der Text erscheinen, wenn das Feld nicht gefüllt wurde und wenn das Feld nicht mit einer syntaktisch richtigen E-Mail-Adresse gefüllt wurde, dann kann für dieses Feld innerhalb eines Formulars wie folgt ein Validator-Tag definiert werden: Das Attribut button definiert dabei den Namen des Button, der die Validierung auslösen soll, das Attribut field das zu validierende Feld und type den Validator-Typ. Die Inhalte der Attribute msginputreq und msginputwrg wurden in diesem Fall mit dem Prefix "Contact.EMail." versehen um die Zugehörigkeit zur Applikation Kontaktformular und zum Feld E-Mail kenntlich zu machen. Diese Konvention hat sich eingebürgert, um schnell erkennen zu können, welcher Konfigurationsschlüssel zu welcher Applikation gehört. Des Weiteren ist es ratsam, die Konfigurationsdateien zu kommentieren.

Die Konfigurationsdatei muss damit bei Betrieb der Applikation in deutscher und englischer Sprache folgenden Inhalt haben:

2.2. Mehrsprachigkeit

Das Framework bietet mehrere Möglichkeiten Applikationen und Module auf Mehrsprachigkeit auszulegen. Zum einen wird die Sprache eines Objekts in jedem DOM-Knoten mitgeführt und der Entwickler hat damit die Möglichkeit sprachabhängige Texte in einem DocumentController einzusetzen, zum anderen gibt es XML-Tags wie

• <html:getstring />
• <template:getstring />
• <form:getstring />

die sprachabhängige Texte aus Konfigurationsdateien an enstprechenden Stellen anzeigen. Im Fall des Kontaktformulars wird eine Mischform eingesetzt. Als Basis für beide Möglichkeiten dient eine gemeinsame Konfigurationsdatei Diese wird mit folgenden Werten gefüllt: Die Werte können damit z.B. per

• <html:getstring namespace="modules::kontakt4" config="language" entry="form.person" />,
• <template:getstring namespace="modules::kontakt4" config="language" entry="form.person" /> oder
• <form:getstring namespace="modules::kontakt4" config="language" entry="form.person" />

ausgelesen werden. Die Beschriftung von Formular-Controls stellt eine zweite Möglichkeit dar, sprachabhängige Texte zur Anzeige zu bringen. In diesem Fall muss im DocumentController Einfluss auf die Beschriftung genommen werden. Dies kann mit folgenden Code passieren:

2.3. Struktur des Moduls

Ähnlich der Struktur des Moduls "comments" wird auch dieses Software unter dem Ordner modules abgelegt. Hierzu dient der Ordner kontakt4, der wie folgt unterteilt wird: Der Ordner biz dient der Ablage der Business-Komponenten (je ein Domain-Objekt für die Daten des Formulars und die Empfänger), im Ordner data ist der Mapper beheimatet, der die Empfänger einliest und der Ordner pres dient zur Ablage der Controller- und Template-Dateien der Präsentationsschicht. Im Ganzen betrachtet soll das Kontaktformular aus den folgenden Dateien bestehen:

• /modules/kontakt4/pres/templates/kontakt.html:
  Die Datei kontakt.html beinhaltet das Hauptdesign und steuert die Ausgabe von Formular oder Dankesseite mit einem <core:importdesign />-Tag.
• /modules/kontakt4/pres/templates/formular.html:
  Die Datei formular.html beinhaltet das Formular.
• /modules/kontakt4/pres/templates/meldung.html:
  In meldung.html ist der Inhalt der Dankesseite definiert.
• /modules/kontakt4/pres/documentcontroller/kontakt_v2_controller.php:
  Für die Ausgabe des Formulars wird ein DocumentController benötigt, der in der Datei kontakt_v2_controller.php enthalten ist.
• /modules/kontakt4/biz/contactManager.php:
  contactManager.php beheimatet die Business-Komponente, die den Ablauf der Software koordiniert.
• /modules/kontakt4/biz/oRecipient.php:
  oRecipient.php beinhaltet das Empfänger-Domain-Objekt.
• /modules/kontakt4/biz/oFormData.php:
  oFormData.php beinhaltet das Domain-Objekt für die Formulardaten.
• /modules/kontakt4/data/contactMapper.php:
  Die Datei contactMapper.php dient zur Definition der Datenschicht-Komponente, die die Empfänger aus der Konfiguration als Domain-Objekte zur Verfügung stellt.

Wie bereits erwähnt müssen darüber hinaus folgende Konfigurations-Dateien vorgehalten werden:

• /config/modules/kontakt4/{CONTEXT}/{ENVIRONMENT}_empfaenger.ini:
  Konfiguration der Empfänger
• /config/tools/form/taglib/{CONTEXT}/{ENVIRONMENT}_formconfig.ini:
  Texte für die Validator-Tags
• /config/modules/kontakt4/{CONTEXT}/{ENVIRONMENT}_language.ini:
  Sprachabhängige Texte.

Die Syntax der Konfigurationsdateien wurde bereits weiter oben diskutiert, die Inhalte werden im Folgenden noch genauer beschrieben.

3. Implementierung des Moduls

In diesem Tutorial soll wieder der TOP-DOWN-Designansatz verwendet werden. Das aktuelle Kapitel beschreibt daher die oben genannten Dateien ausgehend von der Präsentationsschicht und in der Reihenfolge der Aufzählung.

3.1. Datei kontakt.html

Die Templatedatei kontakt.html definiert das Grundgerüst des Moduls. Es beinhaltet die Überschrift, die per <html:getstring />-Tag aus der Sprach-Konfigurationsdatei eingebunden wird, und einen <core:importdesign />- Tag, der einen View definiert, der entweder das Formular (Standard) oder eine Dankesmeldung anzeigt: Hinweis: Im Template wird das <core:importdesign />-Tag mit der pagepart-Option benutzt. Dies bedeutet, dass je nach URL-Parameter pagepart ein anderes Template aus den angegebenen Namespace eingebunden wird. Ist kein Parameter in der URL vorhanden wird die im Attribut template angegebene Templatedatei - das Formular - eingebunden.

3.2. Datei formular.html

Die hier behandelte Templatedatei enthält im Wesentlichen vier unterschiedliche Blöcke:

• Definition des DocumentControllers (Zeile 1)
  Hier wird definiert, welcher Controller (MVC-Controller für den aktuellen DOM-Knoten) zur Transformation herangezogen wird.
• Einbindung von weiteren TagLibs: (Zeilen 2-3)
  Um die Tag-Library "html:form" bzw. "html:getstring" nutzen zu können müssen diese zunächst mit einem "core:addtaglib"-Tag eingebunden werden.
• Definition der HTML-Inhalte: (Zeilen 5-9)
  In den Zeilen 5 bis 9 wird das HTML-Grundgerüst des Formular-Views definiert. Dieser beinhaltet einen Hinweistext, der mit einem <html:getstring />-Tag eingebunden wird und einen <html:placeholder />-XML-Tag, der später vom DocumentController mit dem Inhalt des transformierten Formulars gefüllt wird.
• Formular: (Zeilen 11-43)
  In den Zeilen 11 bis 43 wird das Formular definiert. Dieses beinhaltet eine Validator-Gruppe, die zur Anzeige der Validierungsmeldungen genutzt wird. Die Beschriftungen werden mit dem <form:getstring />-Tag uns der oben beschriebenen Konfigurationsdatei realisiert.

3.3. Datei meldung.html

In der Datei meldung.html wird die Dankesmeldung definiert, die bei erfolgreichem Absenden des Formulars eingeblendet wird. In der Regel ist das ein Satz, der besagt, dass der Kunde baldige Rückantwort erhalten werden. In diesem Fall wird die Meldung aus einer Konfigurationsdatei gelesen, die einen mehrsprachigen, aber statischen Text enthält. Aus diesem Grund ist kein weiterer DocumentController notwenig.

3.4. DocumentController kontakt_v4_controller

Der DocumentController kontakt_v4_controller erbt vom abstrakten DocumentController base_controller (Interface). Auf Grund der Objekt-Struktur muss dies immer gegeben sein, die übrige Gestaltung der Klasse bleibt jedoch dem Programmierer überlassen. Es ist somit jederzeit möglich eigene Methoden zu definieren und weitere eigene Klassen per import() hinzuzuladen und zu verwenden. Im Fall des Kontakt-Formulars wird zum Aufbau des Formular-Views die private Methode __buildForm() verwendet. Zu Steuerung der Ausgabe des Designs kontakt.html wird die öffentliche Methode transformContent() implementiert. Sie beschreibt, dass das Formular so lange angezeigt wird, bis alle als Pflichtfelder gekennzeichneten Eingabe-Felder mit validen Werten ausgefüllt sind (siehe Zeile 60). Tritt dieser Fall ein, so wird die Business-Schicht instanziert, das Formular abgeschickt und der Bestätigungsview (Templatedatei meldung.html) angezeigt. Bei näherer Betrachtung der Klasse kontakt_v4_controller wird deutlich, dass der DocumentController die Komponenten RequestHandler und contactManager verwendet. Die zuerst genannte Klasse ist eine im Framework integrierte Klasse, die für die Extraktion von REQUEST-Variablen verwendet wird und nicht im Request enthaltene Variablen mit Standard-Werten belegen kann. Details zu dieser Komponente können der Klassenreferenz entnommen werden. Die zweite Komponente ist die Business-Schicht des Kontaktformulars. Sie stellt der Präsentations-Schicht eine Schnittstelle zum Laden von Empfängern und Abschicken des Formulars zur Verfügung.

3.4.1. Methode transformContent()

In der Methode transformContent() findet die Generierung der Darstellung statt. Hierzu wird eine Referenz auf das Formular-Objekt geholt und anschließend geprüft, ob das Formular abgeschickt wurde und die Eingaben valide sind. Ist das nicht der Fall, wird der oben erwähnte Platzhalter mit der Formularausgabe gefüllt. Sind die Eingaben valide, so wird ein Form-Daten-Objekt erzeugt und mit Werten gefüllt. Anschließend wird die Business-Komponente mit Hilfe der privaten Methode __getServiceObject() erzeugt und die Methode sendContactForm() mit dem DomainObjekt oFormData als Parameter aufgerufen und das Formular abgesendet. Das Verschicken der Daten per Mail und die Weiterleitung wird dabei von der Businessschicht übernommen.

3.4.2. Methode __buildForm()

Die Funktion __buildForm() wird vom Autor gerne als "Helper-Funktion" bezeichnet, da siese lediglich die Ausgabe des Formulars kapselt. Die Methode übernimmt jedoch drei Aufgaben: Zuerst muss das action-Attribut mit dem für das Modul gültigen URL versehen werden, anschließend wird die Bild-URL für das Warnungs-Symbol der Validator-Gruppe gesetzt und schließlich das Select-Feld mit den Empfängern gefüllt. Weiterhin muss der Button des Formulars noch mit einem sprachabhängigen Wert beschriftet werden.

Setzen des action-Attributes:
Da jedes Objekt von "APFObject" erbt, besitzt dieses - genau wie das Form-Objekt - die Methode setAttribute(). Mit Hilfe dieser Funktion kann damit das Attribut action des Formular-Objektes gesetzt werden.

Konfigurieren der Validator-Gruppe:
Um den Platzhalter "WarnBild" und "WarnText" in der Validator-Gruppe setzen zu können, holt sich der Entwickler zunächst eine Referenz auf dieses Objekt. Im internen DOM ist die Validator-Gruppe ein Kind-Objekt des Formulars. Um eine Referenz auf ein Kind-Element zu bekommen, muss der Entwickler zunächst eine gültige Referenz auf das Formular-Objekt besitzen. Anschließend stehen die Methoden getFormElementByName() und getFormElementByID() zur Verfügung. Die Klasse, die die Funktion der Validator-Gruppe repräsentiert, besitzt gemäß API-Dokumentation die Methode setPlaceHolder(). Mit Hilfe dieser Funktion kann ein Platzhalter der Validator-Gruppe gefüllt werden.

Im Fall des "WarnImage" und "WarnText" werden sprachabhängige Konfigurationsdateien verwendet. Die URL des Warnhinweis-Bildes und der zugehörige Text befinden sich dabei in der Konfigurationsdatei unter der Sektion [de] (für deutsche Sprache) und dem Schlüssel Um einen sprachabhängigen Wert aus der Konfiguration zu lesen wird die Sektion über die interne Membervariable $this->__Language gesteuert, die je nach gewählter Sprache den entsprechenden zweistelligen ISO-Ländercode beinhaltet, der als Titel für die Sprachsektion in der Konfigurationsdatei gewählt wurde. Im vorliegenden DocumentController wird das Füllen der beiden Platzhalter per erledigt.

Zum Schluss der Methode wird das Formular transformiert und an die aufrufende Methode zurückgegeben.

3.5. Klasse contactManager

Die Klasse contactManager ist eine Implementierung der Business-Schicht. Sie kapselt die eigentliche Geschäfts-Logik der Anwendung und kommuniziert mit weiter unten liegenden Schichten (Daten-Schicht oder weitere Treiber-Schichten). Im Fall des Kontakt-Formulars wird in der Business-Schicht das Formular abgesendet oder Empfängerdaten geladen. Dazu stehen der Präsentations-Schicht zwei öffentliche Methoden zur Verfügung: sendContactForm() um ein Formular abzusenden und loadRecipients() um Empfänger zu laden. Die Schnittstelle zwischen diesen beiden Schichten bilden die Domain-Objekte oFormData und oRecipient. In den ersten beiden Zeilen werden wiederum Komponenten aus dem Framework eingebunden, die später für den Mailversand (mailSender)und das Generieren von Links (LinkHandler) verwendet werden.
In der Methode sendContactForm() werden zwei ServiceObjekte initialisiert, die für den Versand notwendig sind: die Datenschicht um das ausgewählte Empfänger-Objekt zu laden und der mailSender um die Bestätigungs- und Benachrichtigungs-Mails zu versenden.
Die Methode loadRecipients() ist der Service für die Präsentationsschicht, die die Empfänger-Objekte läd.

4. Klasse contactMapper

Die Klasse contactMapper ist eine Implementierung des DataMapper-Patterns und dient der Business-Schicht um Daten aus der Empfänger-Konfigurationsdatei in Form von Domain-Objekten zur Verfügung zu stellen. Dazu läd der Mapper die Daten zunächst mit Hilfe der Funktion __getConfiguration() aus der Konfigurations-Datei und mappt dies anschließend in Empfänger-Domänen-Objekte (oRecipient). Die Konfigurationsdatei selbst ist mit mehreren Sektionen der Form aufgebaut. Die Methode loadRecipients() mappt dabei jede Sektion in ein Domain-Objekt (oRecipient) und liefert eine Liste dieser zurück. Jeder Empfänger kann beim Versenden des Formulars an Hand seiner eindeutigen ID (siehe Sektionsnamen) referenziert und per loadRecipientById() geladen werden.
Wird als Quelle keine Konfigurations-Datei, sondern eine Datenbank verwendet, muss lediglich die Implementierungen der Daten-Schicht-Methoden dahin geändert werden, dass die Daten aus der Datenbank statt aus der Datei gelesen werden.

Kommentare

QUICKNAVI

• Alle Releases
• Roadmap
• Subversion repository
• Bugtracking
• Why APF?
• Artikel
• Wiki
• RPM-Installations-HOWTO
• Partner-Seiten
• APF auf SourceForge.net

• Impressum
• Kontakt
• Datenschutzrichtlinien
• Rechtliche Hinweise
• Security
• Lizenz

Adventure PHP Framework (APF) is a product developed by the APF Developer Team. It's released under the GNU Lesser General Public License (LGPGL)
Commercial use is permitted.

Copyright © 2009 Adventure PHP Framework
All textual content on this site is protected by Copyright Law and may be used under the Terms of the GNU Free Documentation License (GNU FDL) See Legal notice for more information.