Formhandler richtig konfigurieren

Grundkonfiguration

TYPO3 Formhandler ist eine sehr mächtige Formular Extension für TYPO3 CMS. Nahezu jeder denkbare Anwendungsfall ist damit zu lösen. Von Formularen die einfach nur per Mail abgeschickt werden zu Einträgen in die Datenbank bis hin zu Newsletteranmeldungen bei externen Dienstleistern wie z.B. Cleverreach ist alles möglich. Ich habe schon viele Formulare mit Formhandler realisiert und kenne das Problem, dass die Einstiegshürde bzw. Lernkurve sehr steil ist. Daher versuche ich euch hier eine kleine Hilfestellung zu geben. Ich werde parallel zu dem wie ich diese Anleitung schreibe das ganze an einer Installation nachvollziehen. Als TYPO3 Version nutze ich die 6.2.12. Diese habe ich installiert und noch nicht weiter konfiguriert.

Als erstes installiere ich die Extension Formhandler. Die aktuelle Version ist 2.0.1. Ich habe eine Root Seite erstellt und in dieser ein TypoScript Template angelegt.

Ich habe nur ein absolutes minimum an TypoScript verwendet. Da es sich hier nur um einen Versuchsaufbau und nicht um eine Webseite handelt die online gehen soll habe ich das TypoScript auf die folgenden Zeilen beschränkt:

page = PAGE
page.10 <  styles.content.get

Dies reicht dafür, dass die Inhalte der Spalte Normal ausgegeben werden.

In der Spalte Normal lege ich nun ein Plugin Element an. Als Plugin wähle ich „Formhandler“ aus.

Rufen wir jetzt das Frontend auf so wird einzig und alleine
An error has occurred!
ausgegeben.

Trotz der Meldung dass ein Fehler aufgetreten ist heißt dies jedoch, dass Formhandler korrekt installiert wurde und arbeitet. Es existiert nun lediglich noch ein Konfigurationsproblem welches wir im nächsten Schritt lösen werden.

Formhandler Konfiguration

Als nächstes legen wir eine Konfiguration für Formhandler an. Der Einfachheit halber wird das TypoScript erst einmal in das normale Template geschrieben. Mir ist bewusst, dass das massive Nachteile hat, für den ersten Demo Zweck reicht das aber erst einmal.
Das folgende TypoScript tragen wir ins Template ein:

plugin.Tx_Formhandler.settings.predef.first-form {

  # This is the title of the predefined form shown in the dropdown box in the plugin options.
  name = My first form
  
  # All form fields are prefixed with this values (e.g. disable-submit[name])
  formValuesPrefix = form
  
  #The "id" attribute of the form. Needed for autoDisableSubmitButton.
  formID = contact-form

  langFile.1 = TEXT
  langFile.1.value = {$formhandler.first-form.rootPath}/lang/lang.xml

  templateFile = TEXT
  templateFile.value = {$formhandler.first-form.rootPath}/html/step-1.html

  # The master template is a file containing the markup for specific field types or other sub templates (e.g. for emails). You can use these predefined markups in your HTML template for a specific form.
  masterTemplateFile = TEXT
  masterTemplateFile.value = {$formhandler.first-form.rootPath}/html/mastertemplate.html

  # In case an error occurred, all markers ###is_error_[fieldname]### are filled with the configured value of the setting "default".
  isErrorMarker {
    default = has-error
  }

  # These wraps define how an error message looks like. The message itself is set in the lang file.
  singleErrorTemplate {
    totalWrap = |
  }
  

  # This block defines the error checks performed when the user hits submit.
  validators {
    1.class = Validator_Default
    1.config.fieldConf {
      name.errorCheck.1 = required
      email.errorCheck.1 = required
      email.errorCheck.2 = email
      message.errorCheck.1 = required  
    }
  }        

  finishers {

    # Finisher_Mail sends emails to an admin and/or the user.
    1.class = Finisher_Mail
    1.config {
      checkBinaryCrLf = message
      admin {
        templateFile = TEXT
        templateFile.value = {$formhandler.first-form.rootPath}/html/email-admin.html
        sender_email = {$formhandler.first-form.email.admin.sender_email}
        to_email = {$formhandler.first-form.email.admin.to_email}
        subject = TEXT
        subject.data = LLL:{$formhandler.first-form.rootPath}/lang/lang.xml:email_admin_subject
      }
    }

    # Finisher_Redirect will redirect the user to another page after the form was submitted successfully.
    5.class = Finisher_Redirect
    5.config {
      redirectPage = {$formhandler.first-form.disable-submit.redirectPage}
    }
  }
}

Diese Konfiguration basiert auf einer Beispielkonfiguration von der Seite http://examples.typo3-formhandler.com/start/ diese ist eine gute Anlaufstelle für einfache Beispiele. Ebenso kann ich die Dokumentation empfehlen.

In dem obigen TypoScript wird auf Konstanten zugegriffen. Die nachfolgende Konfiguration habe ich für die Constants eingetragen:

formhandler.first-form {

  # cat=Formhandler - First Form/basic/10; type=string; label=Root path: Path where the example was saved to.
  rootPath = fileadmin/formhandler/first-form/
  
  email {
    admin {
      # cat=Formhandler - First Form/basic/20; type=string; label=Admin email sender: Email address to use as sender address for the admin email.
      sender_email = 

      # cat=Formhandler - First Form/basic/20; type=string; label=Admin email recipient: Email address of an admin to receive the contact request.
      to_email = 
    }
  }

  # cat=Formhandler - First Form/basic/40; type=string; label=Redirect Page: Page ID to redirect after successful form submission.
  redirectPage = 
  

}

Mit dem TypoScript und den Constants ist die Konfiguration für das Formular abgeschlossen.

Im TypoScript haben wir zuerst einmal den Namen sowie das formValuePrefix, also den Namespace der übertragenen Parameter definiert. Anschließend ist die Sprachdatei, das Template sowie ein Master Template angegeben. Die Mastertemplate Datei beinhaltet Schnipsel, welche in der Templatedatei verwendet werden können. Die Templatedatei gibt vor, welche Felder in dem Formular vorhanden sind.

Anschließend gibt es noch die Konfiguration für isErrorMarker. Dieser beinhaltet den Text, welcher ausgegeben wird wenn ein Validierungsfehler aufgetreten ist. In diesem Fall füllt Formhandler ein paar Platzhalter im Template die genutzt werden können. Die Konfiguration isErrorMarker.default füllt den Platzhalter ###is_error_[fieldname]###, welcher im Template verwendet werden kann.

Die Konfiguration singleErrorTemplate definiert welcher Inhalt um die Fehlermeldungen für die einzelnen Felder gewrappt werden soll.

Der nächste größere Block im TypoScript, der validators Block beschreibt welche Validatoren ausgeführt werden sollen nachdem das Formular abgeschickt wurde. In dem Beispiel sind name, email und message Pflichtfelder. Außerdem muss das email Feld eine gültige E-Mail beinhalten.

Der letzte Block im TypoScript, finishers beschreibt was passieren soll nachdem das Formular abgeschickt wurde und die Validatoren erfolgreich durchlaufen wurden. Das ausgefüllt Formular wird per E-Mail verschickt und der Besucher anschließend auf eine Danke Seite die in den Constants eingetragen wird weitergeleitet. Diese abschließenden Konfigurationen, also die Mail und die Weiterleitung auf die Danke Seite sind im Abschnitt finishers im TypoScript konfiguriert.

Wir wechseln jetzt zurück zum Plugin. Auf dem Tab Plugin ganz unten unter Predefined forms steht in der Select Box jetzt ein weitere Eintrag zur Verfügung. Wir wählen dort „My first form“ aus.

Das Template

Die Mastertemplate Datei die in dem Beispiel verwendet wird habe ich im Anhang als Download zur Verfügung gestellt.

Das Template (step-1.html) beinhaltet den folgenden Inhalt:

<!-- ###TEMPLATE_FORM1### -->
###master_multipart-form-start_contact-form###
###master_section-start###
###master_input_ajax_name###
###master_input_ajax_email###
###master_textarea_ajax_message###
###master_section-end###
###master_section-start###
###master_submit-disable###
###master_section-end###
###master_form-end###
<!-- ###TEMPLATE_FORM1### -->

dabei gibt es einige wichtige Bereiche. Das fängt mit dem Kommentar in der ersten und der letzten Zeile an. Dieser muss immer genau so sein. Der einzige Variable Teil daran ist die nummer. Diese beschreibt bei einem mehrstufigen Formular den Step des Formulares. Die zweite sowie alle weiteren Zeilen beziehen sich auf das Master Template. Es wird jeweils ein bestimmter Teil aus dem Master Template gerendert. Die Zeile zwei rendert z.B. den folgenden Bereich der Master Template Datei

class="container">

Die Zeile zwei der Template Datei beinhaltet neben dem Master Template Platzhalter als Suffix noch den String _contact-form. Dieser String finden ohne den führenden Unterstrich in den Platzhalter ###fieldname### im Mastertemplate Verwendung. Man befüllt diesen Platzhalter also damit.

Neben den Dateien für das Template (step-1.html) sowie der Datei mastertemplate.html gibt es noch die Datei email-admin.html. Diese beinhaltet das Template für die Email die durch den Finisher_Mail verschickt wird. Das Template besitzt den folgenden Inhalt:

<!-- ###TEMPLATE_EMAIL_ADMIN_PLAIN### -->
###master_email-admin-start-plain###
###master_email-line-plain_name###
###master_email-line-plain_email###
###master_email-line-plain_message###
###master_email-admin-end-plain###
<!-- ###TEMPLATE_EMAIL_ADMIN_PLAIN### -->

<!-- ###TEMPLATE_EMAIL_ADMIN_HTML### -->
###master_email-admin-start-html###
###master_email-line-html_name###
###master_email-line-html_email###
###master_email-line-html_message###
###master_email-admin-end-html###
<!-- ###TEMPLATE_EMAIL_ADMIN_HTML### -->

Hier sind auch wieder die Kommentare sehr wichtig, diese legen die einzelnen Bereiche des Templates fest. Ansonsten beinhaltet das Template eine Start sowie eine abschließende Zeile. Es wird in diesem Template ebenfalls wieder auf das Master Template zugegriffen. Der Platzhalter ###master_email-line-plain_name### ist wieder zweigeteilt zu betrachten. Zum einen wäre da der erste Teil ###master_email-line-plain, welcher den Part in der Master Template Datei beschreibt. Der zweite Teil name### wird wieder als ###fieldname### in der Master Template Datei aufgelöst. In der Master Template Datei wird mit einem kleinen Trick auf den Wert des entsprechenden Formularfeldes zugegriffen.
In der Master Template Datei steht ###value_###fieldname###### . der Platzhalter ###fieldname### entspricht für das erste Feld dem Strin „name“. Somit wird in der Template Datei der Platzhalter ###value_name### ersetzt.

Die 3 Template Dateien werden in den Ordner /fileadmin/formhandler/first-form/html gespeichert.

Localization

Es gibt noch eine Sprachdatei mit folgendem Inhalt:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<T3locallang>
	<meta type="array">
		<description>Language labels for first-Form</description>
	</meta>
	<data type="array">
		<languageKey index="default" type="array">
			<label index="label_fieldset">First Form</label>
			<label index="name">Name:</label>
			<label index="email">E-Mail:</label>
			<label index="message">Your Message:</label>
			<label index="captcha">Captcha - SPAM Protection</label>
			<label index="submit">Send</label>
			<label index="greetings">Dear</label>
			<label index="email_user_subject">Your contact request</label>
			<label index="email_user_text">We have received your request via the contact form on www.example.org. We will process your request and get in contact with you soon.</label>
			<label index="email_user_footer">---------------------------------- This message was created automatically. --------------------------------</label>
 
			<label index="email_admin_subject">Contact request</label>
			<label index="email_admin_text">A user filled out the contact form on www.example.org.</label>
			<label index="email_admin_footer">---------------------------------- This message was created automatically. --------------------------------</label>
 
			<label index="error_name_required">Please enter your name!</label>
			<label index="error_email_required">Please enter your email address!</label>
			<label index="error_email_email">Please enter a valid email address!</label>
			<label index="error_message_required">Please enter a message!</label>
		</languageKey>
	</data>
</T3locallang>

Interessant sind an dieser Datei die letzten 4 Zeilen. Für jede Validator Konfiguration sollte ein entsprechendes label angelegt werden. Der index des Labels setzt sich dabei wie folgt zusammen. Als erstes der String error, gefolgt von dem Namen des Feldes, also z.B. name. Abschließend wird der entsprechende Validator angefügt. Als komplettes Beispiel z.B. error_name_required. Die lang.xml Datei wird in dem Ordner fileadmin/formhandler/first-form/lang/ gespeichert. Mit dieser Konfiguration sollte das Formular nun im Frontend angezeigt werden.

Fragen

Solltet ihr noch Fragen haben oder sollte das bei euch nicht funktionieren, so hinterlasst mir eine Nachricht. In einem späteren Artikel werde ich euch beschreiben wie ihr die eingegebenen Daten in der Datenbank speichert.