Have a look in the /tx_thmailformplus/example_form/ directory. You will find the following files there:
mailformplus_demo.html ... single form example with file upload
multipage.html ... multipage form example with fileupload and error checks
multipage_conditions.html ... multipage form with different routes depending on user input.
multipage_TypoScript_setup.txt ... TS for multipage.html example
multipage_conditions_TypoScript_setup.txt ... TS for multipage_conditions.html example
plugin.tx_thmailformplus_pi1.saveLog = 1
plugin.tx_thmailformplus_pi1.saveLog {order = price,first_name , surename,email,phone,message,freeCD
defaultValue= 0
exclude = x,y, id
}
Let's say you want to have a dropdown filed in a form showing all departments of your company and you want a email to be sent to the head of the department when a user fills out the form and submits it.
What we need:
a page having the departments as subpages
use the “subtitle” field of the department pages to store the email-addresses for each department.
place a placeholder ###pulldown_departments### in the right place of your HTML-template
... then put this code to your TypoScript setup:
temp.jsmenu = HMENU
temp.jsmenu.special = directory
temp.jsmenu.special.value = 123 # page ID having departments as subpages
temp.jsmenu.1 = TMENU
temp.jsmenu.1 {expAll = 0
wrap = <select name="email_to" class="form_dropdown"><option value="no department selected" class="form_dropdown">please select a department</option>|</select>
NO {before.data = field:subtitle
before.wrap = <option value="|" class="form_dropdown">
doNotLinkIt = 1
allWrap = | </option>
}
CUR < .NO
CUR = 1
CUR.before.wrap = <option value="|" SELECTED class="form_dropdown">
}
plugin.tx_thmailformplus_pi1.markers.pulldown_departments < temp.jsmenu
(since 3.5.0)
Many of you know the problem: you use the same mailformplus element several times within one project showing the form on several pages. After changing the form-HTML-template you have to edit each mailformplus element and assign the changed template once more in order to make the changes visible.
Or if you are using several mailformplus elements that are all sent to one email address: if that email address changes, you have to search and edit every mailformplus element on the page.
The default settings specified via TypoScript are the default values of the mailformplus element but are overridden by the settings you enter in the mailformplus element.
If you leave the field blank in the mailformplus element, the default value defined in TypoScript is used.
You can do tricky things with that like:
changing the required fields (checked server side) depending on a radio button the user selected in the form.
Let's say, you give the user the possibility to check if he wants to be contacted via email or via telephone.
Of course you also have the two input fields in the form, but when the user checks “email”, the email field has to be filled out. If the user checks “telephone”, the telephone field is required.
this is how it's done:
[globalVar = GP:contact_me_via=email]
plugin.tx_thmailformplus_pi1.default.email_requiredfields = email,name
[end]
[globalVar = GP:contact_me_via=telephone]
plugin.tx_thmailformplus_pi1.default.email_requiredfields = tel,name
[end]
result if the user selected “email” and submitts the form:
result if the user selected “telephone” and submitts the form:
(available since 3.7, thx to Martin Kutschker)
This hook gives you the possibility to save or process the submitted fields after the form was successfully submitted.
Standard mailformplus functionality like sending mail(s) or inserting records are not influenced by this hook.
how to use the hook:
define a user-function which will do the processing
create a php file with a class and function which will be called when the form was submitted:
file:
class.tx_myext.php
file content:
class tx_myext {function doit(&$params, &$ref){......
}
}
The variable $params will hold the following values:
$params[config] ... config variables passed via TypoScript: example: saveUserFunc.dummy = hello can be accessed by $params[config][dummy]
$params[data] ... all submitted GET and POST variables merged
activate the hook with TypoScript
You have to define the user function that should be called when the form was submitted correctly:
plugin.tx_thmailformplus_pi1.saveUserFunc = EXT:myext/class.tx_myext.php:tx_myext->doit
You can also define “variables” which will be passed to the user function:
plugin.tx_thmailformplus_pi1.saveUserFunc.dummy = hello
(available since 4.0.0, thx to Maik Vlcek)
This hook gives you the possibility to validate specific fields with your own function.
Standard mailformplus functionality are not influenced by this hook.
How to use the hook:
1.) define a user-function which will do the validation
create a php file with a class and function which will be called for defined
fields when the form was submitted:
file:
class.user_myvalidation.php
file content:
class user_myvalidation {function user_validate(&$params, &$ref){$input = $params['value'];
switch($params['checkFor']){case "telephonenumber":
/* first way to do it */
$errorFound = preg_match("/[\+]?([0-9]+[\s]?)+/",$input);return $errorFound;
/* extended version with custom error messages */
if(strlen($input) < 1){ $error = array("errorFound"=>1,"errorText"=>'Please fill out this field');}
else{ $errorFound = preg_match("/[\+]?([0-9]+[\s]?)+/",$input); $error = array("errorFound"=>$errorFound,"errorText"=>'Please enter a valid telephone number');
}
return $error;
break;
...
}
}
}
The variable $params will hold the following values:
$params['value'] ... the value of the field to be validated
$params[nameOfParameterInTypoScript] ... valueOfParameterInTypoScript
example: if you defined
plugin.tx_thmailformplus_pi1.fieldConf.[name of inputfield].errorCheck = userValidation
plugin.tx_thmailformplus_pi1.fieldConf.[name of inputfield].errorCheck{checkFor=telephonenumber
}
then $params['checkFor'] will be "telephonenumber"
As you can see in the example above, there are two possible return values
1. boolean (0 or 1)
2. array ("errorFound"=>boolean, "errorText"=>"Here you can put your customerror message which will override TS Settings");
The $errorFound(boolean) must be false or 0 if no error was found and vice versa
Version 2 gives you the ability to display more descriptive error messages
depending on the input to improve usability (see example)
2.) activate the hook with TypoScript
First you have to define the user function that should be used for custom
valitation:
plugin.tx_thmailformplus_pi1.errorUserFunc = EXT:myext/class.user_myvalidation.php:user_myvalidation->user_validate
Then you'll have to define the fields which should be validated with your user
function:
plugin.tx_thmailformplus_pi1.fieldConf.[name of inputfield].errorCheck=userValidation
plugin.tx_thmailformplus_pi1.fieldConf.[name of inputfield].errorCheck{checkFor=telephonenumber
param2=ger
}
If you want to show the user a summary of the submitted form (after it was successfully submitted) to give him/her the possibility to print out what he/she filled out, you have to define this ###TEMPLATE_PRINT### subpart.
Note:
the PRINT-subtemplate has to be HTML.
this functionality only makes sense if you do a redirect to a “thank you” page – otherwise you can fill the ###TEMPLATE_SUBMITTED_OK### subtemplate showing a summary of the submitted form.
After the form got submitted, the replaced PRINT-subtemplate is stored in the user-session.
To show the summary on the page, you have to fetch the session value with a user-function and print it out on the page.
example PRINT-subtemplate:
<!-- ###TEMPLATE_PRINT### begin -->
You just filled out the following fields:<br>
Name: ###name###<br>
Subject: ###subject###<br>
<br>
you uploaded the following files:
###photo###
<br>
###cv###
<br>
<!-- ###TEMPLATE_PRINT### end -->
example User-func for fetching the session value:
see th_mailformplus/example_form/mailformplus_userfunc.inc.php
example TypoScript for fetching the value
includeLibs.mailformplus_functions = fileadmin/mailformplus_userfunc.inc.php
################################
# outputs the PRINT template below normal page content
# main content
################################
temp.main_content = COA
temp.main_content {10 < styles.content.get
20 = USER
20.userFunc = user_mailformplus_userfunc->user_mailformplusPrint
}
...
page.10.subparts.CONTENT_MAIN < temp.main_content
(available since version 4.0.4 | Very special thanks to Stephan Bauer <stephan_bauer(at)gmx.de> for the code)
In your HTML-Template you are able to wrap the field output in e-mails and subpart ###TEMPLATE_SUBMITTED_OK### with a subpart:
<!-- ###ISSET_FAX### -->
###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### -->
###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### -->
###EMAIL###
<!-- ###ISSET_EMAIL### -->
<!-- ###ISSET_email### -->
###email###
<!-- ###ISSET_email### -->
bad:
<!-- ###ISSET_EMAIL### -->
###email###
<!-- ###ISSET_EMAIL### -->
<!-- ###ISSET_email### -->
###EMAIL###
<!-- ###ISSET_email### -->
(available since version 4.0.0)
In the template file:
Specify markers for the multi language texts.
example:
###TEMPLATE_FORM###
<!-- ###TEMPLATE_FORM### begin -->
<form name="Formular" method="post" action="###REL_URL###" enctype="multipart/form-data">
<input type="hidden" name="id" value="###PID###">
<input type="hidden" name="submitted" value="1">
<input type="hidden" name="L" value="###value_L###">
<input type="hidden" name="type" value="###value_type###">
<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###
Your custom language file:
deprecated:
$LOCAL_LANG = Array (
'default' => Array (
'username' => 'username:',
'password' => 'password:',
'submit' => 'Login',
),
'dk' => Array (
),
'de' => Array (
'username' => 'Benutzername:',
'password' => 'Passwort:',
'submit' => 'Anmelden',
),
'no' => Array (
),
);
Please use XML:
<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<T3locallang>
<meta type="array">
<type>module</type>
<description>Language labels for plugin "tx_kkmailformpluslist_pi1"</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:
plugin.tx_thmailformplus_pi1.langFile = [path to language file]
(available since version 4.0.0)
Define the needed subpart in your HTML-Template
Example (taken from the online manual of sr_freecap):
<!--###CAPTCHA_INSERT### this subpart is removed if CAPTCHA is not enabled! -->
<div class="tx-your-extension-id-pi1-captcha">
<label for="tx_your_extension_id_pi1_captcha_response">###SR_FREECAP_NOTICE###</label>
###SR_FREECAP_CANT_READ###
<br />
<input type="text" size="15" id="tx_your_extension_id_pi1_captcha_response" name="captchafield" title="###SR_FREECAP_NOTICE###" value="">
###SR_FREECAP_IMAGE###
</div>
<!--###CAPTCHA_INSERT###-->
Typoscript:
Define the sr_freecap field
plugin.tx_thmailformplus_pi1.freecapFieldname = [fieldname]
Example:
plugin.tx_thmailformplus_pi1.freecapFieldname = captchafield
Other sr_freecap specific setting must be defined with the typoscript settings of sr_freecap. See the manual of sr_freecap for further details.
(available since version 4.0.0)
First of all, please register an account on http://recaptcha.net/. You will get a public key and a private key. Add these to your typoscript template:
plugin.tx_jmrecaptcha {
public_key = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
private_key = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
}
Add a marker ###RECAPTCHA### to your html template.
Enable usage of recaptcha via typoscript:
plugin.tx_thmailformplus_pi1.useRecaptcha = 1
TS:
plugin.tx_thmailformplus_pi1.saveDB = 1
plugin.tx_thmailformplus_pi1.saveDB {useDifferentDB = 1
useDifferentDB {driver = oracle
host = 192.168.0.3
port = 1521
user = root
password = something
table = my_address_storage
saveFields = titel,vorname,zuname,strasse,plz,ort,telefon,katalog,email,refer,client_ip
}
dbTable = addresses
dbkey = uid
fields {title.mapping = titel
firstname.mapping = vorname
lastname.mapping = zuname
street.mapping = strasse
zip.mapping = plz
city.mapping = ort
phone.mapping = telefon
email.mapping = email
country.mapping = staat
catalog0.mapping = katalog
catalog0.preProcessing = USER
catalog0.preProcessing.userFunc = user_mfp_funcs->user_mergeCatalogFields
referer.mapping = refer
}
specialMapping = 1
specialMapping.logIP = client_ip
}
The submitted values get stored into the table “addresses” in the TYPO3 DB.
Only the fields listed in “saveFields” get stored into the other db table. That's needed because the other db table will not have fields like pid, hidden, deleted, ...
