EXT: Universal Formhandler¶

What does it do?¶

When you reach the limits of the standard mailform functionality of TYPO3 (especially when you want the form to look special) you can use this extension to use your conventional HTML-forms (as HTML-snippets) with full mailform functionality.

This extension is considered as the follow-up to th_mailformplus, including nearly all the features of th_mailformplus and many more new features having a completely new architecture and code. The result is a very flexible approach to form handling.

The new architecture and TypoScript configuration makes it possible to easily control the processing of the form by adding an infinite number of validators and interceptors to filter form input. After successful form submission you can add special interceptors to sanitize input values for final processing in the so called “finishers”. Finishers are used to save data into DB, send emails, redirect to another page, etc. Have a look at the available classes described in this manual. If you miss a feature, you can easily write your own class and plug it into MailformPlus MVC processing. After having read the manual and looked into the code documentation, you will see how your own classes can be integrated into MailformPlus MVC.

Please visit the extension's section on forge to post feature requests or report bugs.

http://forge.typo3.org/projects/show/extension-mailformplusplus

Note : This extension requires PHP 5.2 or higher and the extension “gimmefive” from Jochen Rau.

Screenshots¶

This is how MailformPlusPlus works. Quite simple, isn't it? For more information about the rendering process have a look at the section “How does this extension work?”.

The Plugin view of MailformPlusPlus. The user can choose a template file and a translation file. Furthermore the user can enter settings for E-mail submission and redirection.

A form generated with MailformPlusPlus having file uploads handling and error checks.

Create template¶

To create a form using MailformPlusPlus you will first have to write a HTML template file containing the code of your form. You will have to follow certain rules, so that MailformPlusPlus will be able to detect the suitable subparts for each situation. For an overview of how to create a form template have a look at the sections “ How to set up a simple form ” and “ Available markers to use in subparts ” or check the demo templates located at EXT:mailformplusplus/Examples/

Create translation file¶

In order to use error messages for your fields and to be able to use multilanguage labels, you have to write a translation file. We decided to make translation files kind of obligatory because it's just nicer. So if you want your form to be fully functional, we recommend to use a translation file. A little tutorial on how to use those translations is in section “ How to set up multilanguage forms ”.

Create a Plugin Record¶

Create a new page and create a content element. Choose type “General plugin”. In the section “Plugin” now choose “MailFormPlusPlus” as plugin type. Now you are able to select your template file and translation file as well as setting options for e-mail sending, basic “required” error checks and a redirect page after successful submission of the form. When creating a new record, the default predefined form is selected. To add your own predefined form, you should add a new TypoScript template.

Enter your options and save.

Create a TypoScript setup¶

If you want to use the whole power of MailformPlusPlus you should use TypoScript to configure your form. Many different examples are available at EXT:mailformplusplus/Examples/

Tips and tricks: It is sometimes more convenient to edit the TypoScript in an external file. This is particularly true for big typoscript chunk. To do this, insert in a suitable typoscript template (can be the root or a local TS template):

<INCLUDE_TYPOSCRIPT: source="FILE:fileadmin/templates/mailform/setup.ts">

Then, you could add this line to your user profile / group to avoid clearing the cache all the time.

admPanel.override.tsdebug.forceTemplateParsing = 1

Include static¶

Don't forget to include the MailformPlusPlus static setup in your root template!

FAQ¶

Feel free to contribute on http://forge.typo3.org/projects/extension- mailformplusplus/issues

How does this extension work?¶

The process of rendering a form got simplified to the following simple tasks:

• Preprocessing:

  Do some work before the form is shown, when the page is loaded for the first time (no submission took place). This can be used to load default values for fields or other tasks.

• Intercepting:

  Before the form is shown, there may be a need to intercept and do something with the previously entered data. Mailformplus MVC uses this for doing XSS checks. Mailformplus MVC knows two types of interceptors, InitInterceptors and SaveInterceptors. InitInterceptors are called everytime before the form is shown, SaveInterceptors are called when the form got submitted successfully right before the Finishers are called.

• Validating:

  After form submission there has to be a possibility to validate the input.

• Finishing

  After successful form submission there may be several tasks to perform, such as saving the input data to database or sending emails.

Any of these mentioned tasks can take more than one class that are called seperately.

A little example:

finishers {
  1 {
    class = Finisher_DB
    config {
    ...
    }
  }
  2 {
    class = Finisher_Mail
    config {
    ...
    }
  }
  3 {
    class = Finisher_Redirect
    config {
    ...
    }
  }
}

As you see, there are several Finishers defined, which perform different tasks. It is kind of a Finisher chain, so that any number of tasks can be performed. The first Finisher will store the submitted data into a defined database table, the second will send emails to users or administrators, the third will redirect to another page. The idea of creating chains of classes is also possible for PreProcessors, Interceptors and Validators.

Reference¶

Important Note:

MailformPlusPlus requires to enter class names of components to perform different tasks.

Example:

finishers.1.class = F3_MailformPlusPlus_Finisher_Mail

To make the usage easier, it is not needed to prefix the classes with F3_MailformPlusPlus_ in TypoScript:

finishers.1.class = Finisher_Mail

<input type="text" name="mailformplusplus[email]" value="###value_email###" />

plugin.F3_MailformPlusPlus.settings {

  # Checkbox fields in step 1
  1.checkBoxFields = interests, hobbies

  # Checkbox fields in step 2
  2.checkBoxFields = work_experience,accounts
}

plugin.F3_MailformPlusPlus.settings {

  # Radiobutton fields in step 1
  1.radioButtonFields = contact_via

  # Radiobutton fields in step 2
  2. radioButtonFields = receive_gift
}

plugin.F3_MailformPlusPlus.settings {
  isErrorMarker {
    global = Global message if an error occurred (filled into ###is_error###)
    field1 = TEXT
    field1.value = Some message (filled into ###is_error_field1###)
  }
}

loggers.1 {
  class = F3_MailformPlusPlus_Logger_Default
}
loggers.2 {
  class = F3_MyPackage_Logger
  config {
    table = tx_mypackage_log
  }
}

preProcessors.1 {
  class = F3_MailformPlusPlus_PreProcessor_Default
}
preProcessors.2 {
  class = F3_MyPackage_ PreProcessor
  config {
    param = value
  }
}

preProcessors {
    1.class = F3_MailformPlusPlus_PreProcessor_LoadDefaultValues
       1.config {
         1 {
            tile.defaultValue = {$local.mailform.title}
            lastname.defaultValue = Firstname in here
            firstname.defaultValue = TEXT
            firstname.defaultValue.value = Lastname in here
         }
         2 {
            creditcard.defaultValue = Enter your credit card number here
         }
       }
}

preProcessors {
    1.class = F3_MailformPlusPlus_PreProcessor_ClearTempFiles
    1.config {
      clearTempFilesOlderThan {
          value = 24
          unit = hours
      }
    }
}

initInterceptors.1 {
  class = F3_MailformPlusPlus_Interceptor_RemoveXSS
}
initInterceptors.2 {
  class = F3_MyPackage_ Interceptor
  config {
    param = value
  }
}

saveInterceptors.1 {
  class = F3_MailformPlusPlus_Interceptor_Default
}
saveInterceptors.2 {
  class = F3_MyPackage_ Interceptor
  config {
    param = value
  }
}

plugin.F3_MailformPlusPlus.settings.initInterceptors.1.class = F3_MailformPlusPlus_Interceptor_RemoveXSS

plugin.F3_MailformPlusPlus.settings.initInterceptors.1.class = F3_MailformPlusPlus_Interceptor_Filtreatment

<input type=”hidden” name=”mailformplusplus[formtime]” value=”###TIMESTAMP###” />

validators.1 {
  class = F3_MailformPlusPlus_Validator_Default

  /*
  * Some times you maybe want to disable error checks if the user
  * filled out a specific fields or else.
  * Temporary disable error checking for the entered fields by setting
  * this option.
  */
  disableErrorCheckFields = firstname,lastname
  config {
    fieldConf {
      firstname.errorCheck {
        1 = required
        2 = maxLength
        2.value = 20
      }
      email.errorCheck {
        1 = required
        2 = email
      }
    }
  }
}
validators.2 {
  class = F3_MyPackage_ Validator
  config {
    param = value
  }
}

finishers.1 {
  class = F3_MailformPlusPlus_Finisher_Mail
  config {
    admin {
      to_email = rf@typoheads.at
      to_name = Reinhard Führicht
      subject = Request
      sender_email = contactform@mysite.com
      replyto_email = email
      replyto_name = name
    }
    user {
      to_email = email
      to_name = name
      subject = ###LLL:user_subject###
      sender_email = contactform@mysite.com
      sender_name = My Site
      replyto_email = contactform@mysite.com
    }
  }
}
finishers.2 {
  class = F3_MailformPlusPlus_Finisher_Default
  config {

  }
}

<!-- ###TEMPLATE_CONFIRMATION### begin -->
<table>
  <tr>
    <td>###LLL:firstname###</td>
    <td>###value_firstname###</td>
  </tr>
</table>
<div>
###PRINT_LINK### / ###PDF_LINK### / ###CSV_LINK###
</div>
<!-- ###TEMPLATE_CONFIRMATION### end -->

fields {
  header {
    preProcessing = USER
    preProcessing.userFunc = user_helper->appendSomething
    mapping = firstname
  }
}

fields {
  header {
    postProcessing = USER
    postProcessing.userFunc = user_helper->appendSomething
    mapping = firstname
  }
}

fields {
  header {
    preProcessing = USER
    preProcessing.userFunc = user_helper->appendSomething
    mapping = firstname
  }
}

fields {
  header {
    postProcessing = USER
    postProcessing.userFunc = user_helper->appendSomething
    mapping = firstname
  }
}

Available error checks¶

The default validator offers a variety of predefined error checks for the most common tasks. Here is a list of the checks and how to configure them:

plugin.F3_MailformPlusPlus.settings.validators.1 {
  class = F3_MailformPlusPlus_Validator_Default
  config {
    fieldConf {
      firstname.errorCheck.1 = required
      firstname.errorCheck.2 = minLength
      firstname.errorCheck.2.value = 4
      firstname.errorCheck.3 = notDefaultValue
      firstname.errorCheck.3.defaultValue = Enter firstname here
      picture.errorCheck.1 = fileRequired
      picture.errorCheck.2 = fileAllowedTypes
      picture.errorCheck.2.allowedTypes = jpg,png,gif,tiff
    }
  }
}

Available subparts to use in the template¶

Available markers to use in subparts¶

<input type=”text” name=”email” value=”###value_email###” />

<option value="webdesign" ###selected_topic_webdesign###>Webdesign</option>

<input type="checkbox" name="topic" value="webdesign" ###checked_topic_webdesign###>Webdesign

<input type="radio" name="contact_via" value="email" style="border-style:none;" ###checked_contact_via_email###>e-mail

How to set up a simple form¶

Create a HTML template file containing your form. Examples can be found in EXT:mailformplusplus/Examples

Create a new page

Create a content element with type “General Plugin”

Choose “MailformPlusPlus” in Dropdown “Plugin”

Check that predefined form "Default" is selected.

Optional: Choose a translation file containing error messages and translations filled into markers ###LLL:[key}###

Optional: Enter settings for E-Mail, required fields or a page to redirect to

Save and view the page

How to set up an advanced form¶

Create a HTML template file containing your form. Examples can be found in EXT:mailformplusplus/Examples

Create a new page

Create an extension template and enter a TypoScript setup entering template file, lang file and other settings.

Create a content element with type “General Plugin”

Choose “MailformPlusPlus” in Dropdown “Plugin”

Save and view the page

NOTE: Configuring your form using TypoScript gives you much more possibilities.

How to use predefined forms¶

Create a TypoScript setup using the predef setting

Example:

plugin.F3_MailformPlusPlus.settings.predef.contactform {
             # This name appears in the dropdown selector in plugin record
             name = Contact form
             ...
             ...
     }

Create a content element with type “General Plugin”

Choose “MailformPlusPlus” in Dropdown “Plugin”

Now you can choose the entered predefined form from the “Predefined forms” dropdown.

Save and view the page.

HINT: they are many examples available at EXT:mailformplusplus/Examples

How to set up a multistep form¶

Create a HTML template file containing your form. Examples can be found in EXT:mailformplusplus/Examples/MultiStep

Create a new page

Create an extension template and enter a TypoScript setup entering template file, lang file and other settings.

Create a content element with type “General Plugin”

Choose “MailformPlusPlus” in Dropdown “Plugin”

Choose “Multi step” from Dropdown “Type”

Save and view the page

NOTE: You can overwrite settings made in plugin.F3_MailformPlusPlus.settings for each step using plugin.F3_MailformPlusPlus.settings.[stepnumber]

How to set up a multistep form with conditions¶

Create a HTML template file containing your form. Examples can be found in EXT:mailformplusplus/Examples/MultiStepConditions

Create a new page

Create an extension template and enter a TypoScript setup entering template file, lang file and other settings.

Create a content element with type “General Plugin”

Choose “MailformPlusPlus” in Dropdown “Plugin”

Choose “Multi step” from Dropdown “Type”

Add TypoScript conditions and change the settings plugin.F3_MailformPlusPlus.settings.[stepnumber].templateSuffix

Save and view the page

How to set up spam protection¶

###error_captchafield###
     ###CAPTCHA###
     <input type="text" name="mailformplusplus[captchafield]" />

plugin.F3_MailformPlusPlus.settings.validators.1 {
       class = F3_MailformPlusPlus_Validator_Default
       config {
         fieldConf {
           captchafield.errorCheck.1 = captcha
         }
       }
     }

<!--###CAPTCHA_INSERT### this subpart is removed if CAPTCHA is not enabled! -->
             <div>
                     <label for="freecapfield">###SR_FREECAP_NOTICE###</label>
             <div class="clear"></div>
            ###SR_FREECAP_CANT_READ###
                     <div class="clear"></div>
                     <input type="text" size="15" id="freecapfield" name="mailformplusplus[freecapfield]"                 title="###SR_FREECAP_NOTICE###" value="">
                     ###SR_FREECAP_IMAGE###
             </div>
     <!--###CAPTCHA_INSERT###-->

plugin.F3_MailformPlusPlus.settings.validators.1 {
       class = F3_MailformPlusPlus_Validator_Default
       config {
         fieldConf {
           freecapfield.errorCheck.1 = srFreecap
         }
       }
     }

plugin.tx_jmrecaptcha {
       public_key = xxx
       private_key = xxx
     }

###error_recaptcha_response_field###
     ###RECAPTCHA###

plugin.F3_MailformPlusPlus.settings.validators.1 {
       class = F3_MailformPlusPlus_Validator_Default
       config {
         fieldConf {
           recaptcha_response_field.errorCheck.1 = jmRecpatcha
         }
       }
     }

###error_mathguard_answer###
     ###MATHGUARD###

plugin.F3_MailformPlusPlus.settings.validators.1 {
       class = F3_MailformPlusPlus_Validator_Default
       config {
         fieldConf {
           mathguard_answer.errorCheck.1 = mathGuard
         }
       }
     }

How to set up error checks¶

Add markers like ###error_[fieldname]### to your template

Set up a validator in TypoScript

plugin.F3_MailformPlusPlus.settings.validators.1 {
       class = F3_MailformPlusPlus_Validator_Default
       config {
         fieldConf {
             field1 {
              errorCheck.1 = required
              errorCheck.2 = maxLength
              errorCheck.2.value = 50
             }
             field2 {
              errorCheck.1 = required
              errorCheck.2 = email
             }
         }
       }
     }

Add entries for error messages to your translation file

<label index="error_field1_required">Field1 is required!</label>
<label index="error_field1_maxLength">Field1 has to be shorter than ###value### characters!</label>
<label index="error_field2_required">Field2 is required!</label>
<label index="error_field2_email">Field2 is no valid e-mail!</label>

NOTE: The marker ###value### in the error message is filled with the value of the parameter “value” for error check “maxLength”. If an error check requires parameters, you can use markers like ###[parametername]### in the translatable message.

###is_error###
###is_error_[fieldname]###

<label index="is_error_field1">Error occurred in field1!</label>

plugin.F3_MailformPlusPlus.settings {
  isErrorMarker {
    global = Global message if an error occurred (filled into ###is_error###)
    field1 = TEXT
    field1.value = Some message (filled into ###is_error_field1###)
  }
}

How to fill your own markers via TypoScript¶

Add the marker into your template

###myMarker###

Register the marker in TypoScript. (3 examples available)

plugin.F3_MailformPlusPlus.settings.predef.myForm.markers.myMarker_1 = TEXT
plugin.F3_MailformPlusPlus.settings.predef.myForm.markers.myMarker_1.value = My marker content

# getText function
plugin.F3_MailformPlusPlus.settings.predef.myForm.markers.myMarker_2 = TEXT
plugin.F3_MailformPlusPlus.settings.predef.myForm.markers.myMarker_2.data = getIndpEnv:HTTP_HOST

# Constant insertion
plugin.F3_MailformPlusPlus.settings.predef.myForm.markers.myMarker_3 = TEXT
plugin.F3_MailformPlusPlus.settings.predef.myForm.markers.myMarker_3.value = {$local.myConstant}

The marker will be filled with “My marker content”

NOTE: You can fill your own markers using any TypoScript object like USER or COA. Just try it out.

How to hide unfilled form field values in templates¶

In your HTML-Template you are able to wrap the field output in e-mails and subpart ###TEMPLATE_CONFIRMATION### with a subpart:

<!-- ###ISSET_fax### -->
  ###value_fax###<br/>
<!-- ###ISSET_fax### -->

If the user filled out the field “fax” in the form, the text will get shown in the e-mails, otherwise it will not be added.

You have the possibility to add some conditions:

<!-- ###ISSET_fax&&phone### -->
  ###value_fax###<br/>
<!-- ###ISSET_fax&&phone### -->
<!-- ###ISSET_fax&&!phone### -->
  ###fax###<br/>
<!-- ###ISSET_fax&&!phone### -->
<!-- ###ISSET_fax||phone### -->
  ###fax###<br/>
<!-- ###ISSET_fax||phone### -->

As you see, you can use the operators (&&,||,!) to do some simple checks.

NOTE: The case of the fieldname in ISSET subpart and marker MUST match.

good:

<!-- ###ISSET_EMAIL### -->
###value_EMAIL###
<!-- ###ISSET_EMAIL### -->
<!-- ###ISSET_email### -->
###value _email###
<!-- ###ISSET_email### -->

bad:

<!-- ###ISSET_EMAIL### -->
###value _email###
<!-- ###ISSET_EMAIL### -->
<!-- ###ISSET_email### -->
###value _EMAIL###
<!-- ###ISSET_email### -->

How to set up multi language forms¶

In the template file:

Specify markers for the multi language texts.

example:

<!-- ###TEMPLATE_FORM### begin -->
<form name="form" method="post" action="###REL_URL###">
<input type="hidden" name="submitted" value="1">

<table>
<tr>
<td>###LLL:username###</td>
<td><input type="text" name="username" value="###value_username###"></td>
</tr>
<tr>
<td>###LLL:password###</td>
<td><input type="password" name="password" value="###value_password###"></td>
</tr>
<tr>
<td colspan=”2”><input type="submit" name="submit" value="###LLL:submit###"></td>
</tr>
</table>
</form>
<!-- ###TEMPLATE_FORM### end -->

Your custom language file:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<T3locallang>
        <meta type="array">
                <description>Language labels for my form</description>
        </meta>
        <data type="array">
                <languageKey index="default" type="array">
                        <label index="username">Username:</label>
                        <label index="password">Password:</label>
                        <label index="submit">Login</label>
                </languageKey>
                <languageKey index="de" type="array">
                        <label index="username">Benutzername:</label>
                        <label index="password">Passwort:</label>
                        <label index="submit">Anmelden</label>
                </languageKey>
        </data>
</T3locallang>

TypoScript:

You can specifiy the path to your translation file in any setting “langFile” associated with “mailformplusplus”.

Example:

plugin.F3_MailformPlusPlus.settings.langFile = fileadmin/lang/myLangFile.xml

How to load data from DB to use in Finisher_DB¶

It may be useful to extend the set of data submitted in the form before inserting them in the database. You may want to fetch additional data from the database, the session, the GET / POST parameters or from something else. This can be done quite easily since the key "mapping" can understand TypoScript.

Let's have a look at the following lines. They are 4 examples, field_demo_1, field_demo_2, field_demo_3, field_demo_4.

2.class = F3_MailformPlusPlus_Finisher_DB
2.config {
    table = tt_content
    key = uid
    fields {

        # Retrieves data from the GET / POST parameters
        field_demo_1 {
            mapping = TEXT
            mapping.data = GPvar:mailformplusplus|firstname
        }

        # Retrieves data from the database
        field_demo_2 {
            mapping = TEXT
            mapping {
                dataWrap = DB:tx_cuso_courses:{GPvar:mailformplusplus|course_uid}:title
                insertData = 1
                wrap3 = {|}
            }
        }

        # Retrieves data from the session
        field_demo_3 {
            mapping = TEXT
            mapping.data = TSFE:fe_user|user|last_name
        }

        # Some more cool stuff
        field_demo_4 {
            mapping = COA
            mapping {
                 10 = TEXT
                 10 {
                     data = GPvar:mailformplusplus|firstname
                 }
                 20 = TEXT
                 20 {
                     data = GPvar:mailformplusplus|lastname
                     noTrimWrap = | |: |
                 }
                 30 = TEXT
                 30 {
                    dataWrap = DB:tx_cuso_courses:{GPvar:mailformplusplus|course_uid}:title
                    insertData = 1
                    wrap3 = {|}
                 }
            }
        }
    }
}

How to use HTML as PDF template¶

This only works if Generator_TCPDF is used.

<!-- ###TEMPLATE_PDF### -->
<table>
        <!-- ###pid###, ###submission_date### and ###ip### are predefined markers to use in this subpart -->
        <tr>
                <td>###LLL:pid###</td>
                <td>###pid###</td>
        </tr>
        <tr>
                <td>###LLL:ip###</td>
                <td>###ip###</td>
        </tr>
        <tr>
                <td>###LLL:submission_date###</td>
                <td>###submission_date###</td>
        </tr>
        <tr>
                <td>###LLL:[fieldname]###</td>
                <td>###value_[fieldname]###</td>
        </tr>
</table>
<!-- ###TEMPLATE_PDF### -->

How to upgrade from th_mailformplus to Mailformplus MVC¶

There are many forms out there which use th_mailformplus. If you ask yourself, what would happen if you did an update to Mailformplus MVC, here is a short explanation on how to change the TypoScript of th_mailformplus to work with MailformplusMVC. This is not a complete tutorial, it only shows the basic differences. Many of the TypoScript settings are named equally, but some also have changed, were removed or didn't exist in th_mailformplus.

A TypoScript setup for th_mailformplus may look like this:

plugin.tx_thmailformplus_pi1 {
        langFile = typo3conf/ext/th_mailformplus/example_form/singlepage_forms/improved_demo_lang.php

        default {
                email_to = admin@host.com
                email_sendtouser = email
                email_subject_user = Your contact request
                email_sender = noreply@host.com
        }

        fieldConf {
                name {
                        errorCheck = required
                }
                email {
                        errorCheck = required,email
                }
                text {
                        errorCheck = required
                }
        }
}

In this configuration a translation file is included, error checks are defined and settings for email sending to an admin and the user are made.

The same configuration with Mailformplus MVC will look this way:

plugin.F3_MailformPlusPlus.settings {
        langFile = typo3conf/ext/th_mailformplus/example_form/singlepage_forms/improved_demo_lang.php

        validators.1.class = Validator_Default
        validators.1.config {
                name {
                        errorCheck.1 = required
                }
                email {
                        errorCheck.1 = required
                        errorCheck.2 = email
                }
                text {
                        errorCheck = required
                }
        }

        finishers.1.class = FinisherMail
        finishers.1.config {
                admin {
                        to_email = admin@host.com
                        sender_email = noreply@host.com
                }
                user {
                        to_email = email
                        sender_email = noreply@host.com
                        subject = Your contact request
                }
        }
}

As you see, the configuration looks similar, but Mailformplus MVC uses blocks like “validators” or “finishers” to make it possible to group any number of classes. So that it is possible to let “finishers.1” be a class to send emails and “finishers.2” be a class to store data into database.

When you compare the TypoScript options of th_mailformplus with Mailformplus MVC you will find out that they are quite similar and you should have no problems with writing configuration for Mailformplus MVC if you knew th_mailformplus before.