Formhandler › How to set up a simple form

How to set up a simple form

Original blog post written by the guys at Netresearch can be found here (in German).

Building forms for data acquisition is a recurring and repetitive task. Mailformplus has been the first choice to quickly build a form in the TYPO3 world. If you ever glanced a peek at the source code of the th_mailformplus extension, however, chances are you fled your computer screen with a barbaric scream on your lips or used the extension despite its code and quickly forgot about the mechanics.

We, the developers of Mailformplus, are aware of these problems and are proud to present a worthy successor to Mailformplus: Formhandler.

Formhandler can do a lot more than just send mails:

Build complex forms, even across several pages
Check values with 40 validators (e.g. email, date, and filetype)
Send emails in plaintext and HTML, save form data to the database, and generate PDFs and CSVs
CAPTCHA integration

Since the configuration of the forms is done in TypoScript it is quite flexible. Additionally, it is really easy to customize Formhandler in PHP in the form of {Finisher|Interceptor|Logger|PreProcessor|Validator}-classes.

In this article we will walk you through the customization of a simple contact form.

Requirements

The form will be used to collect customer requests and feedback and forward it to the appropriate contact person.

Form elements:

A dropdown to select the contact person. Contact persons are frontend users that belong to a particular group.
A textfield: customer name and email
The message of the customer to the contact person

Form validation:

All fields must be filled
The message must have a certain minimum length
The customer email must be valid

Further processing of the data:

Sending the message to the contact person
Sending of a copy of the message to the customer
Displaying a "Thank you" message with a link to the starting page

General notes on Formhandler

With formhandler there is no need to add var_dump()-statements to the code. It is sufficient to set debug=1 and in addition to that activate the admin panel for TypoScript debugging:

config.admPanel=1
plugin.Tx_Formhandler.settings.debug=1

Forms consist of 2 or 3 files: the TypoScript configuration, HTML template, and a language file with error messages and labels. It is easiest to place these in a single folder in fileadmin/.

Integrating the form in Typo3

Install Formhandler via the extension manager
Create a new page in the page tree
Add the Formhandler plugin but do not set any preferences
In the main menu in the backend (left) click on "Template" and create an extension template
- Title: +ext contactform
- Setup: <INCLUDE_TYPOSCRIPT: source="FILE:fileadmin/contactform/1-contactform.ts">
Create the TypoScript file you have just linked to:fileadmin/contactform/1-contactform.ts
Create the HTML file: fileadmin/contactform/1-contactform.html

You have now prepared everything to get down to the nitty gritty of creating the form in formhandler.

1st version: A simple form

The first version will just be a simple form with name, email, and text. Upon finishing the form there will be an email sent out to a specified admin.

TypoScript

plugin.Tx_Formhandler.settings {   
  debug = 1    
  templateFile = fileadmin/contactform/1-contactform.html  
  formValuesPrefix = formhandler    
  finishers {     
    1 {       
      class = Finisher\Mail     
    }     
    2 {       
      class = Finisher\SubmittedOK       
      config.returns = 1     
    }   
  } 
}

HTML

<!-- ###TEMPLATE_FORM1### begin -->
<p>If you are experienceing any troubles, please let us know:</p>
<form action="###REL_URL###" id="projektform" method="post" class="formhandler">
 <dl>
  <dt><label for="message">Message</label></dt>
  <dd>
   <textarea name="formhandler[message]" id="message">###value_message###</textarea>
  </dd>
 
  <dt><label for="sender_name">Your Name</label></dt>
  <dd>
   <input type="text" name="formhandler[sender_name]" id="sender_name"
          value="###value_sender_name###" />
  </dd>
 
  <dt><label for="sender_email">Your email address</label></dt>
  <dd>
   <input type="text" name="formhandler[sender_email]" id="sender_email"
          value="###value_sender_email###" />
  </dd>
 </dl>
 <input type="submit" value="Submit" ###submit_nextStep### />
</form>
<!-- ###TEMPLATE_FORM1### end -->
 
<!-- ###TEMPLATE_SUBMITTEDOK### begin -->
<p>The following message has been sent:</p>
<p>###value_message###</p>
<!-- ###TEMPLATE_SUBMITTEDOK### end -->
 
<!-- ###TEMPLATE_EMAIL_ADMIN_PLAIN### begin -->
The following contact form has been sent to you:
Sender: ###value_sender_name### ###value_sender_email###
Text:
###value_message###
<!-- ###TEMPLATE_EMAIL_ADMIN_PLAIN### end -->

Now, all you have to do is enter the admin email adress in the the plugin preferences under "Admin email settings" and you have a completely functional form!

2nd version: Including validation

After setting up the bare essentials, we will now turn to validation and displaying error messages.

Data validation is realized in Formhandler with validators. The standard validator Validator_Default is quite powerful and includes what you will need for everyday purposes:

validators.1.class = Validator\DefaultValidator
validators.1.disabled = 0
validators.1.config.fieldConf {
  message.errorCheck.1 = required
  message.errorCheck.2 = minLength
  message.errorCheck.2.value = 5
 
  sender_name.errorCheck.1 = required
 
  sender_email.errorCheck.1 = required
  sender_email.errorCheck.2 = email
}

With this little bit of TypoScript you are all done: The message needs to be 5 characters long, the name must not be empty, and the email must be a valid email address.

In order to display error messages you will have to include some markers in the HTML template:

###ERROR###
List of all error messages

###error_$fieldname###
Specific error message for the field $fieldname

If you include the error markers into the template as is they look rather unappealing since they are displayed without any kind of formatting. Use a little bit of TypoScript to remedy that:

addErrorAnchors = 1
singleErrorTemplate {
  totalWrap = |
  singleWrap = <span style="color: red;">|</span>
}
errorListTemplate {
  totalWrap = <div style="color: red;">Es sind folgende Fehler aufgetreten: <ul>|</ul></div>
  singleWrap = <li>|</li>
}

With this the single error messages will be displayed in red and the list of all error messages ues a list tag.

If you try out the form at this point you will notice that there will be debug messages like

Could not find error message with key "error_message_required"!

Error messages are stored in a language file which uses the popular XML dialect T3locallang. You include the language file like this:

langFile = fileadmin/contactform/3-lang.xml

The file itself includes key-value-pairs with the messages:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<T3locallang>
 <data type="array">
  <languageKey index="default" type="array">
   <label index="error_message_required">There is no message</label>
   <label index="error_message_minLength">The message is too short</label>
 
   <label index="error_sender_name_required">Your name is missing</label>
 
   <label index="error_sender_email_required">Your email is missing</label>
   <label index="error_sender_email_email">Your email is invalid</label>
  </languageKey>
 </data>
</T3locallang>

You now have a form with error messages that you can translate into any language you require.

3rd version: Adding a Contact person

Up to this point we have relied on setting the recipient email in the plugin preferences. One of the required features of our example form is that each customer can choose whom he or she would like to send the email to.

To keep the form easy on maintenance we will not be including static values in the form, but rather fetch the values from our database. The frontend user table fe_users is perfect for our requirements, as it includes name and email and the users can easily be grouped according to our needs.

In preparation of this step you need to set up a frontend user group ("contact form recipients", in this example with uid 3) which includes a few users with name and email. Additionally, the recipient email must be removed from the plugin preferences, otherwise the TypoScript configuration would overridden.

It is a good idea to enable the TYPO3 admin panel in the front end for this.

#typoscript debugging
config.admPanel = 1

With TypoScript -> "Display messages" and "Explain SELECT queries" it is now quite easy to sniff out any troubles with the SQL configuration in TypoScript.

We will be accessing the users in the usual way via SQL via TypoScript using a CONTENT object. Formhandler allows the use of markers in the template, one of which we will be using to get the <option> tags with names and emails into the template:

markers.options_recipient = CONTENT
markers.options_recipient {
  table = fe_users
  select {
    #pid where feusers are stored
    pidInList = 29
    orderBy = name
    selectFields = email, name
    #contact form user group
    where = 3 IN (fe_users.usergroup)
    max = 10
  }
  renderObj = COA
  renderObj {
    #value
    10.wrap = <option value="|"
    10 = TEXT
    10.field = email
 
    #selected
    12.noTrimWrap = | ###selected_recipient_|###>|
    12 = TEXT
    12.field = email
 
    #label
    13 = TEXT
    13.value = {field:name} ({field:email})</option>
    13.insertData = 1
  }
}

Using table and select we specify what it is we need from the database. The renderObj generates an <option value="e@ma.il"> tag which automatically receives selected="selected" when the appropriate email is selected.

Now we need to add a marker with a surrounding <select> tag into the HTML:

<dt><label for="recipient">Recipient</label></dt>
<dd>
 ###error_recipient###
 <select name="formhandler[recipient]" id="recipient" size="1">
  <option value="">- no recipient chosen -</option>
  ###options_recipient###
 </select>
</dd>

... and validate the recipient:

recipient.errorCheck.1 = required
recipient.errorCheck.2 = email

Now you will need to let the mail finisher know that the email should go to the selected email address:

class = Finisher\Mail
config.admin {
  to_email = TEXT
  to_email.data = GP:formhandler|recipient
  subject = TEXT
  subject.data = LLL:fileadmin/contactform/4-lang.xml:mail_subject_admin
}

That's it. You're done. The emails will now go to the appropriate addresses.

4th version: Make it pretty

Now that you have implemented all the core functionality it is time to prettify the form by:

Sending a copy of the email to the customer
Using texts and labels from the language file, so the form can be translated more easily
Adding a link back to the starting page

Using translations in Formhandler is extremely simple: Just add ###LLL:name_of_my_label### into the HTML template and the corresponding text will be fetched from the lang.xml you have set up in the second version of the form.

Setting up the email copy to the customer is as simple as:

config.user {
  to_email = TEXT
  to_email.data = GP:formhandler|sender_email
  subject = TEXT
  subject.data = LLL:fileadmin/contactform/4-lang.xml:mail_subject_user
}

To add a link to the starting page we simply configure another marker and set it up with a typolink:

markers.backlink = TEXT
markers.backlink {
  value = startingpage
  typolink.parameter = 6
}

We will now use this marker insider the SUBMITTEDOK block of the HTML template:

Return to ###backlink###

Final notes

With just a little bit of TypoScript, an HTML template and a language file you can set up a multi language contact form with database connections in a matter of minutes. Please refer to the documentation for the rest of the Formhandler features.