DEPRECATION WARNING
This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.
EXT: TMailform¶
Author: | Kasper Skårhøj |
---|---|
Created: | 2002-11-01T00:32:00 |
Changed by: | Sebastian Busch |
Changed: | 2007-07-13T15:32:47 |
Email: | typo3-dev@billiton.de |
Info 2: | |
Info 3: | |
Info 4: |
EXT: TMailform¶
Extension Key: pil_mailform
Copyright 2007, Sebastian Busch <typo3-dev@billiton.de>
Copyright 2005-2007, <typo3@pil.dk>
This document is published under the Open Content License
available from http://www.opencontent.org/opl.shtml
The content of this document is related to TYPO3
- a GNU/GPL CMS/Framework available from www.typo3.com
Table of Contents¶
EXT: TMailform 1
Introduction 1
What does it do? 1
Screenshots 1
Configuration 1
Workflow 1
Flexform reference 1
TypoScript reference 1
Known problems 1
To-Do list 1
Changelog 1
Suggestions from users not yet implemented 1
Introduction¶
What does it do?¶
The TMailform provides an easy way to put a mailform on your website without loosing control over design of the mailform. It uses templates and is easily configured via flexfoms - thus not a single line of typoscript is necessary.
This extension was originally written by Tonni Aagesen (pil.dk).
With the language and in particular database support in version >3.0.0, this extensions potential has in reality outgrown is original purpose. It can for example be used for registering/manipulating frontend users, newsletter subscriptions... any not too complex manipulation of data - use your imagination :)
Key features are:
- Template based- freedom in design
- Easy configuration through flexform
- Multiple serverside validation methods for required fields
- Error message pr. field
- Recipient email addresses are not shown in page/source
- Retrieve/store values in database
Screenshots¶
Unfortunately, I was only able to put in one screenshot to avoid exceeding the 100kb extension upload limit. There will be more screenshots available at http://t3dev.pil.dk sometime soon.
Configuration¶
The TMailform extension mainly uses configuration through template and flexform. By configuration through template I mean that the form template subpart play a role in the setup through the naming of the form fields as we will see later on. In fact, the concept of TMailform is, that markers are generated dynamically from the form fields name attributes accordingly.
If you find yourself confused by the concept, don't worry. Just remember this rule of thumb; In order to be processed, all form fields name attribute must be of this form “tx_pilmailform_pi1[<field type>][<field name>]”, where <field type> corresponds to the form field type and <field name> is the fields name identifier. In example, this would be a correct form field:
<input type=”text” name=”tx_pilmailform_pi1[text][subject]” />
The <field name>, in this case “subject”, is recognized by TMailform and the extension will create up to three template markers when the form is submitted. The first marker will be created as “###SUBJECT_VAL###”, and will be substituted with the value from the field. If you have specified this field to be required and the field was empty when the form was submitted, a second marker “###SUBJECT_ERR###” will be created. This marker will be substituted with what you have specified in the flexform. Also, if you have defined an error message for a specific required field, a marker “###SUBJECT_ERR_TXT###” will be created and substituted with the specified message.
If the form is submitted and the required fields, specified by you, are not empty, values from the form fields will be available as markers in the MAIL and MAIL_USERCOPY subparts in “###<field name>_VAL###” notation.
Simple, right? There is, however, some special cases where the above description doesn'texactly apply. I will explain theseby example in the workflow section.
Workflow¶
To setup TMailform you will first have to determine which information you wish to gather from the form. In the following I will describean example workflow. An example template is included with this extension.
Creating a template¶
In this example I wish to gather the following information from the user:
- The user's name
- The user's email address
- Whether the user represents a private person or a company
- The user's Typo3 experiencelevel
- The user's job description
- The subject of the user's inquiry
- The message from the user
- A resume as an attached file
Further I wish direct the email to a relevant recipient email address, and provide the user with an option of receiving a copy of the message.
Now, the name, email and subject are pretty straight forward, but we can do some magic with thesefields, as I will explain in the last part of this workflow example. I want thesefields to be just standard input fields of the type text, and I want the fields to be required. So my template will look like this:
<td class=”###SUBJECT_ERR###”>
###SUBJECT_ERR_TXT###
<input type=”text” name=”tx_pilmailform_pi1[text][subject]” value=”###SUBJECT_VAL###” />
</td>
<td class=”###NAME_ERR###”>
###NAME_ERR_TXT###
<input type=”text” name=”tx_pilmailform_pi1[text][name]” value=”###NAME_VAL###” />
</td>
<td class=”###EMAIL_ERR###”>
###EMAIL_ERR_TXT###
<input type=”text” name=”tx_pilmailform_pi1[text][email]” value=”###EMAIL_VAL###” />
</td>
Similar we can add the message from the user as a textarea field type:
<td class=”###MESSAGE_ERR###”>
###MESSAGE_ERR_TXT###
<textarea name=”tx_pilmailform_pi1[textarea][message]”>###MESSAGE_VAL###”</textarea>
</td>
Next, we want to know if the user represents a private person or a company. For this purpose I will use the radio field type:
<td class=”###USER_TYPE_ERR###”>
###USER_TYPE_ERR_TXT###
<input type="radio" name="tx_pilmailform_pi1[radio][user_type]" value="private" ###USER_TYPE_PRIVATE_VAL### /> Private
<br />
<input type="radio" name="tx_pilmailform_pi1[radio][user_type]" value="buisness" ###USER_TYPE_BUISNESS_VAL### /> Buisness
</td>
Did you notice the difference in the value markers? Because the radio field type can have multiple choices, we have to determine which field was selected. The TMailform do this by naming thesemarkers by the field value, thus if the selected field have the value “private” a marker “###USER_TYPE_PRIVATE_VAL###” is created. We can generalize this so that multiple choicefield types generate markers in the form “###<field name>_<field value>_VAL###.
In our example, if the user select “Private” then a marker “###USER_TYPE_PRIVATE_VAL###” is created and substituted with 'checked=”checked”'.
Continuing, we want to know the user's Typo3 experiencelevel. We will now use a selectbox as field type:
<td class=”###LEVEL_ERR###”>
###LEVEL_ERR_TXT###
<select name="tx_pilmailform_pi1[select][level]">
<option value="">Choose best fit</option>
<option value="Beginner" ###LEVEL_BEGINNER_VAL###>Beginner</option>
<option value="Advanced" ###LEVEL_ADVANCED_VAL###>Advanced</option>
<option value="Expert" ###LEVEL_EXPERT_VAL###>Expert</option>
</select>
</td>
Because this also is a multiple choicefield, the same value marker substitution principle as for radio buttons applies. If the user doesn'tmake a choiceor chooses the “Choose best fit” option, the TMailform recognizes this as an field validation error, and the error marker will be substituted. This action is taken because that option has no value (value=””).
Now, we also wanted to gather information about which kind job descriptions, that fits our user. We want to take into consideration, that the user might fit into more than one of the descriptions we provide. For this purpose we will use a selectbox again – only difference is that we allow the user to make more than one choice.
<td class=”###JOBDESCRIPTION_ERR###”>
###JOBDESCRIPTION_ERR_TXT###
<select name="tx_pilmailform_pi1[select][job_description][]" multiple="multiple">
<option value="Developer" ###JOB_DESCRIPTION_DEVELOPER_VAL###>Developer</option>
<option value="Sales person" ###JOB_DESCRIPTION_SALES_PERSON_VAL###>Sales person</option>
<option value="Manager" ###JOB_DESCRIPTION_MANAGER_VAL###>Manager</option>
</select>
</td>
There is only a slight difference between this code and the code for user level selectbox. Of course, we add 'multiple=”multiple”' to make more than one choicedoable. But, we also put an extra empty set of “[]” in the name field of the selectbox. We have to do this to make TMailform recognize all choices, that the user has made. Also notice, that spaces is allowed in the value=”” field, we just have to substitute the spaces with underscores in the value markers.
And so, done with the template! “Hmm... what about the recipient and user copy of message. And, where is the magic you have been talking about?”, I hear you whisper. Well, since the recipient and “user copy” are also somewhat magical, I will merge thesetopic into this next section.
For now, you can put this into your template and save the file somewhere under fileadmin/:
<td class="###FILE1_ERR###">
###FILE1_ERR_TXT###
<input type="file" name="tx_pilmailform_pi1[file][file1]" />
</td>
<td class="###FILE2_ERR###">
###FILE2_ERR_TXT###
<input type="file" name="tx_pilmailform_pi1[file][file2]" />
</td>
<td class=”###MULTI_RECIPIENT_ERR###”>
<select name="tx_pilmailform_pi1[select][multi_recipient]">###MULTI_RECIPIENT_OPTIONS###</select>
</td>
<td>
<input type="checkbox" name="tx_pilmailform_pi1[checkbox][user_copy]" value="yes" ###USER_COPY_YES_VAL### />
</td>
<td colspan="2">
<input type="submit" name="tx_pilmailform_pi1[submit][submit]" value="Send!" />
</td>
Note: If you are using javascript to submit the form, the “tx_pilmailform_pi1[submit][submit]” must be set.
The magic revealed - setting up the extension¶
Well, magic might be a strong word to use, but never the less we can do some pretty neat stuff as I will show now. I assume that you have downloaded and installed the TMailform extension from the repository and inserted it on some page. This section is best read, if you keep the screenshotsection nearby.
In the following the “magic fields” will be explained:
Field: [subject]¶
TMailform gives you the option of specifyinga static subject or let the user provide a subject. If you enable “Subject user override” in the flexform, the value of the [subject] field will be set as subject of the mail.
Field: [name], [surname] and [email]¶
You can set the “From” and “Reply-To” mail headersfrom user specified information. If you enable “”From” user override” and “”Reply-To” user override”, the value of [name], [surname] and [email] fields will be used to set mail headers. Moreover, an [email] field will be checked for a valid email address if the field is not empty.
Field: [multi_recipient]¶
In the flexformyou can choose either a static recipient or allow user to select a recipient. As shown in the template example, you can put a “###MULTI_RECIPIENT_OPTIONS###” marker in your template. This marker will be replaced with the options specified in the flexform.
Any line in flexform textareacontaining a semicolon will be recognized as “<text>;<email>” an options are generated accordingly. Lines with no semicolon will be regarded as a “no value option” (value=””).
In addition, when the form is submitted, an extra marker “###MULTI_RECIPIENT_OPTVAL_VAL###” is created, which will have the value of the text in the selected “<option>text</option>”.
Field: [user_copy]¶
In the flexform you can set if the user should receive a copy of the mail or you can let the user decide. If TMailform is configured to “User select”, the extension will look for a [user_copy] field value and send a copy to the user if a valid email address is specified by the user.
And so, all that is left to do is specify the template, we have created previously, and begin testing the TMailform. For the purpose of testing the mailform, you can set the extension in “test mode” and no mail will be sent. The mail will instead be shown in your browser along with some information about headers etc.
Extra markers that might come in handy for TMAIL_FORM subpart¶
Any field in the fe_user table can set as markers (“###_FEUSER_*###”) in the template subpart, Which FE-user information you have available depends on your fe_user table. Some examples:
###_FEUSER_USERNAME###
###_FEUSER_EMAIL###
###_FEUSER_WWW###
Extra markers that might come in handy for TMAIL_MAIL* subparts¶
###_DATE### Date of mail sent
###_TIME### Time of mail sent
###_SITE### Site name
###_PATH### Page path
###_PAGE### Page title
###_PID### Page ID
###_IP### Client IP
Multiple languages and markers¶
As of version 3.0.0 you can easily use multiple languages in TMailform. All you have to do, is create a locallang xml file and put it somewhere in fileadmin tree (an example file is provided). In your template you can now use language markers.
The concept of language markers is “###_LL_<lang key>###”, where <lang key> is an languageKey index from your locallang xml file. It is as simple as that :)
Working with fields and values¶
In the “Field settings” tab you will find a relatively simple, yet powerful, way of handling fields and values. In the following I will explain the syntax of mapping field values to/from functions.
Each line in “Required values”, “Default values” and “Store Values” consists of three sections separated by semicolons:
field_value[,field_value]; method[:parameter]; [processor:parameter[:parameter]]
Let us take a look each section:
- “field_value[,field_value]” - This section represents any value marker generated by TMailform. In some cases, eg. In storing values, this can be a comma separated list of value markers.
- “method[:parameters]” - This section defines which method that should handle the value marker(s). Some methods requires parameters.
- “[processor:parameter[:parameter]]” - This section defines how to process the data relative to the method section. In some cases this section is optional. If present, the processor takes one or more parameter(s).
Please have a look at the flexform and typoscript reference for examples.
Note: You can put in a comment by setting the first character to # (eg. “# This is a comment”), and this line will not be parsed.
Version 3.0.0 of TMailform offers methods to do some simple interactions with the database. During install of TMailform, you will get the possibility to set how and which tables and fields, that TMailform may access. It is not possible, due to a limitation in EM, to show how you can configure access for multiple tables, but the syntax is:
<table1>:<field1>,...,<fieldN>;...; <tableN>:<field1>,...,<fieldN>
Note: Invalid queries are logged using t3lib_div::sysLog and you can set the behavior of sysLog using Install Tool.
Field/value parser reference¶
Method¶
Required values
Method
Parameters
Parameters
Processor
Processor
Parameters-2
Parameters
Notes
Notes
notEmpty¶
Required values
notEmpty
Parameters
None
Processor
text
Parameters-2
string
Notes
“string” can be any text you want to display in case of a validation error.
“lang key” is an array key from the locallang_template.php file.
A regular expression result can be negated by adding prefix “!”. Some Examples:
- “Require an integer in field value”:
regex:/[0-9]/; text: Need an integer
- “Require that field value does not contain an integer”:
regex:!/[0-9]/; text: Please any remove integers
lang¶
Required values
lang
Parameters
lang key
notEquals¶
Required values
notEquals
Parameters
marker
Useful if submitting a password, and you want to confirm it. Example: “NAME_VAL”
Processor
text
Parameters-2
string
lang¶
Required values
lang
Parameters
lang key
inList¶
Required values
inList
Parameters
Comma separated list of values (item1,item2,...,itemN)
Processor
text
Parameters-2
string
lang¶
Required values
lang
Parameters
lang key
regex¶
Required values
regex
Parameters
Regular expression (perl compatible).
Processor
text
Parameters-2
string
lang¶
Required values
lang
Parameters
lang key
Method¶
Required values
Method
Parameters
Parameters
Processor
Processor
Parameters-2
Parameters
Notes
Notes
plain¶
Required values
plain
Parameters
None
Processor
text
Parameters-2
string
Notes
“String” can be any text you want to display in case of a validation error.
mark¶
Required values
mark
Parameters
predefined marker
Processor
Any predefined marker. Example: _FEUSER_USERNAME
db¶
Required values
db
Parameters
None
Processor
get
Parameters-2
table:field[,field]:where clause
Notes
See “Store values” section of this table.
Method¶
Required values
Method
Parameters
Parameters
Processor
Processor
Parameters-2
Parameters
Notes
Notes
db¶
Required values
db
Parameters
None
Processor
get
Parameters-2
table:field[,field]:where clause
Notes
The generated SQL-queries are grouped by where clauses, and since SQL- statement “INSERT” takes no where clause, we need an unique identifier pr. Query. The identifier must be prefixed with a asterix (*)
It is entirely possible have one query spanning over multiple lines, if they operate on the same database table and have the same where clause. Example:
NAME_VAL; db; new:tx_pilmailform_log:name:*1
EMAIL_VAL; db; new:tx_pilmailform_log:email:*1
equals:
NAME_VAL,EMAIL_VAL; db; new:tx_pilmailform_log:name,email:*1
Both will only generate this single query:
INSERT INTO tx_pilmailform_log (name,email) VALUES (NAME_VAL, EMAIL_VAL);
Note: The parser can only handle one expression pr. where clause.
Note: The generated queries are shown when in TMailform is in testmode.
new¶
Required values
new
Parameters
table:field[,field]:unique identifier
add¶
Required values
add
Parameters
table:field[,field]:where clause
update¶
Required values
update
Parameters
table:field[,field]:where clause
Flexform reference¶
FField:¶
General
FField:
Data type
Data type:
Description
Description:
Default
Default:
Testmode¶
General
Testmode
Data type
Check
Description
If checked, information about the mail be shown in the browser and NO mail is sent.
Default
Unchecked
Static subject¶
General
Static subject
Data type
String
Description
Defines a static subject for the mails. You can use markers in this field.
Default
Empty string
Subject user override¶
General
Subject user override
Data type
Check
Description
If checked, the static subject will be overridden by field ['text']['subject']
Default
Unchecked
User subject prefix¶
General
User subject prefix
Data type
String
Description
If set, the user subject will be prefixed with this. You can use markers in this field.
Default
Empty string
Use recipient¶
General
Use recipient
Data type
Select
Description
Use either static recipient(s) or dynamic recipient of the mail
Default
“static recipient”
Static recipient(s)¶
General
Static recipient(s)
Data type
String
Description
Send mail to this/these email address(es). Each line is expected to be a valid email address.
Default
Empty string
Dynamic recipient¶
General
Dynamic recipient
Data type
String
Description
A recipient is defined by “<name in HTML select box>;<valid email address>”. Any line not containing a semicolon, is treated as a “string only” option in the select box.
Default
Empty string
Copy to user¶
General
Copy to user
Data type
Select
Description
No: User will not receive a copy of the mail.
Yes: User will receive a copy.
User select: If a field ['checkbox']['user_copy'] is detected as checked, a copy will be sent to the user.
Default
“No”
User copy subject¶
General
User copy subject
Data type
String
Description
If not empty, the user copy of the mail will have this string as subject. If left empty, the subject will be the same as the original mail.
Default
Empty string
Template¶
General
Template
Data type
String
Description
Path to template file
Default
Empty string
Multiple language support¶
General
Multiple language support
Data type
Check
Description
Check this to enable multiple language support. Requires a locallang file.
Default
Locallang file¶
General
Locallang file
Data type
String
Description
Path to locallang file
Default
Field:¶
General
Field:
Data type
Data type:
Description
Description:
Default
Default:
Replace error markers with¶
General
Replace error markers with
Data type
String
Description
Any ###<field name>_ERR### markers will be replaced with this string.
Default
Empty string
Required Values¶
General
Required Values
Data type
String
Description
Validates fields by a user defined method. Each line consists of three sections “ field ; validation ; response ” (separated by semicolon). “validation” and “response” can each be divided into two parts themselves: “ field; method:expression; error_key:error_msg >” (separated by colon).
In depth:
- field is the field name.
- method can be one of notEmpty (no expression applies), inList (expression: comma separated list of strings, eg. “str1, strN”) or regex (expression: perl regular expression, eg. (“/^test.*/”).
- error_key can only be text at this point. error_msg is the string which the ###<field name>_ERR_TXT### marker will be replaced with, if the field does not validate.
Example:
SUBJECT_VAL; notEmpty; text: Please fill in subject field
SUBJECT_VAL; regex:/^test.*/; text: Subject must start with "test"
MESSAGE_VAL; notEmpty; text: Please fill in message field
FILE1_VAL; notEmpty; text: Please send file
FILE1_VAL; inList: image/png, text/plain; text: Filetype not allowed
USER_TYPE_VAL; notEmpty;
LEVEL_VAL; notEmpty; text: Please select level
Note: For field type “file” the check is perfomed on the file mime-type.
Default
Empty
Default values¶
General
Default values
Data type
String
Description
Makes it possible to set some default values for the fields in the template. For the fields in the example template, that comes with TMailform, you can do:
NAME_VAL; plain; text:Tonni Aagesen
EMAIL_VAL; plain; mark:FEUSER_EMAIL
JOB_DESCRIPTION_DEVELOPER_VAL; plain; text:selected=”selected”
USER_COPY_YES_VAL; plain; text:checked=”checked”
SUBJECT_VAL; db; get:pages:title:uid=_PID
Default
Empty String
Store values¶
General
Store values
Data type
string
Description
Makes it possible to store values when the form is submitted. Here is some examples:
# INSERT
NAME_VAL,EMAIL_VAL; db; new:tx_pilmailform_log:name,email:*1
# UPDATE/INSERT
EMAIL_VAL,NAME_VAL; db; add:tt_address:email,name:email=EMAIL_VAL
# UPDATE
NAME_VAL; db; update:fe_users:name:uid=_FEUSER_UID
Default
Empty string
Date marker format¶
General
Date marker format
Data type
String
Description
Date representation – see http://php.net/manual/en/function.strftime.php
Default
%Y-%m-%d
Time marker format¶
General
Time marker format
Data type
String
Description
Same as dateMarker
Default
%T
Field:¶
General
Field:
Data type
Data type:
Description
Description:
Default
Default:
“From” name¶
General
“From” name
Data type
String
Description
The name part of the “From:” header.
Default
Empty string
“From” email¶
General
“From” email
Data type
String
Description
The email part of the “From:” header.
Default
Empty string
“From” header user override¶
General
“From” header user override
Data type
Check
Description
If checked, the fields ['text']['name'] and ['text']['email'] will be used to generate the “From:” header.
Default
Unchecked
“Reply-To” name¶
General
“Reply-To” name
Data type
String
Description
The name part of the “Reply-To:” header.
Default
Empty string
“Reply-To” email¶
General
“Reply-To” email
Data type
String
Description
The email part of the “Reply-To:” header.
Default
Empty string
“Reply-To” header user override¶
General
“Reply-To” header user override
Data type
Check
Description
If checked, the fields ['text']['name'] and ['text']['email'] will be used to generate the “Reply-To:” header.
Default
Unchecked
Header name override format¶
General
Header name override format
Data type
Select
Description
If field ['text']['surname'] exists, set format of name override accordingly.
Default
“name surname”
Disclose recipient email in user copy¶
General
Disclose recipient email in user copy
Data type
Check
Description
if checked, the “From:” and “Reply-To:” headers will be set to the first static or dynamic recipient.
Default
Unchecked
“Cc” addresses¶
General
“Cc” addresses
Data type
String
Description
Send mail as “Cc” to this/these email address(es). Each line is expected to be a valid email address.
Default
Empty string
“Bcc” addresses¶
General
“Bcc” addresses
Data type
String
Description
Send mail as “Bcc” to this/these email address(es). Each line is expected to be a valid email address.
Default
Empty string
Content-Transfer-Encoding¶
General
Content-Transfer-Encoding
Data type
Select
Description
Set the mails “Content-Transfer-Encoding” header.
Default
“8bit”
Content-Type¶
General
Content-Type
Data type
Select
Description
Sets if mail should be a HTML mail / plain text mail. These are defined as different subparts in the template -
Note : Selecting HTML mail still requires a template subpart for a plain text mail, else you will leave users with text based email client in the dark.
Default
“text/plain”
Charset¶
General
Charset
Data type
String
Description
Sets the Charset header parameter.
Default
$GLOBALS['TSFE']->renderCharset
Send mail using¶
General
Send mail using
Data type
Select
Description
Choose a method for sending the mail.
PHP mail(): Standard php mail() function.
sendmail: Use the sendmail daemon directly.
smtp: Use a user defined smtp server.
Default
“PHP mail()”
Path to sendmail¶
General
Path to sendmail
Data type
String
Description
The path to the sendmail executable.
Default
“/usr/sbin/sendmail”
SMTP host¶
General
SMTP host
Data type
String
Description
The SMTP hostname to connect to.
Default
“localhost”
SMTP port¶
General
SMTP port
Data type
Integer
Description
The SMTP port to connect to.
Default
25
Use SMTP authentication¶
General
Use SMTP authentication
Data type
Check
Description
If checked, the username and password will be used for the SMTP connection.
Default
Unchecked
SMTP username¶
General
SMTP username
Data type
String
Description
The SMTP username
Default
Empty string
SMTP password¶
General
SMTP password
Data type
String
Description
The SMTP password
Default
Empty string
TypoScript reference¶
Note: The TS values will overwrite flexform values.
TS¶
General
TS
Data type
Data type:
Description
Description:
Default
Default:
testmode¶
General
testmode
Data type
Int
Description
If set to 1, information about the mail be shown in the browser and NO mail is sent.
Default
staticSubject¶
General
staticSubject
Data type
String
Description
Defines a static subject for the mails. You can use markers in this field.
Default
overrideSubject¶
General
overrideSubject
Data type
Int
Description
If set to 1, the static subject will be overridden by field ['text']['subject']
Default
userSubjectPrefix¶
General
userSubjectPrefix
Data type
String
Description
If set, the user subject will be prefixed with this. You can use markers in this field.
Default
typeofRecipient¶
General
typeofRecipient
Data type
Int
Description
0 = static recipient(s)
1 = dynamic recipient
Default
staticRecipient¶
General
staticRecipient
Data type
String
Description
Send mail to this/these email address(es). Each line is expected to be a valid email address. Example
plugin.tx_pilmailform_pi1.staticRecipient (
user@mail.domain.tld
)
Default
dynamicRecipient¶
General
dynamicRecipient
Data type
String
Description
A recipient is defined by “<name in HTML select box>;<valid email address>”. Any line not containing a semicolon, is treated as a “string only” option in the select box. Example
plugin.tx_pilmailform_pi1.dynamicRecipient (
Please select recipient
user@mail.domain.tld
user@mail.domain.tld
)
Default
copyToUser¶
General
copyToUser
Data type
Int
Description
0 = No: User will not receive a copy of the mail.
1 = Yes: User will receive a copy.
2 = User select: If a field ['checkbox']['user_copy'] is detected as checked, a copy will be sent to the user.
Default
userCopySubject¶
General
userCopySubject
Data type
String
Description
If not empty, the user copy of the mail will have this string as subject. If left empty, the subject will be the same as the original mail.
Default
template¶
General
template
Data type
String
Description
Path to template file
Default
useLL¶
General
useLL
Data type
Int
Description
0 = enable multiple languages
1 = disable multiple languages
Default
LLFile¶
General
LLFile
Data type
String
Description
Path to locallang file
Default
TS:¶
General
TS:
Data type
Data type:
Description
Description:
Default
Default:
errorSubstitution¶
General
errorSubstitution
Data type
String
Description
Any ###*_ERR### markers will be replaced with this string.
Default
requiredValues¶
General
requiredValues
Data type
String
Description
Validates fields by a user defined method. Each line consists of three sections “ field ; validation ; response ” (separated by semicolon). “validation” and “response” can each be divided into two parts themselves: “ field; method:expression; error_key:error_msg >” (separated by colon).
In depth:
- field is the field name.
- method can be one of notEmpty (no expression applies), inList (expression: comma separated list of strings, eg. “str1, strN”) or regex (expression: perl regular expression, eg. (“/^test.*/”).
- error_key can only be text at this point. error_msg is the string which the ###<field name>_ERR_TXT### marker will be replaced with, if the field does not validate.
Example:
plugin.tx_pilmailform_pi1.requiredValues (
SUBJECT_VAL; notEmpty; text: Please fill in subject field
SUBJECT_VAL; regex:/^test.*/; text: Subject must start with "test"
MESSAGE_VAL; notEmpty; text: Please fill in message field
FILE1_VAL; notEmpty; text: Please send file
FILE1_VAL; inList: image/png, text/plain; text: Filetype not allowed
USER_TYPE_VAL; notEmpty;
LEVEL_VAL; notEmpty; text: Please select level
)
Note: For field type “file” the check is perfomed on the file mime-type.
Default
defaultValues¶
General
defaultValues
Data type
String
Description
Makes it possible to set some default values for the fields in the template. For the fields in the example template, that comes with TMailform, you can do:
plugin.tx_pilmailform_pi1.defaultValues (
NAME_VAL; plain; text:Tonni Aagesen
EMAIL_VAL; plain; mark:FEUSER_EMAIL
JOB_DESCRIPTION_DEVELOPER_VAL; plain; text:selected=”selected”
USER_COPY_YES_VAL; plain; text:checked=”checked”
SUBJECT_VAL; db; get:pages:title:uid=
)
Default
storeValues¶
General
storeValues
Data type
String
Description
plugin.tx_pilmailform_pi1.storeValues (
# INSERT
NAME_VAL,EMAIL_VAL; db; new:tx_pilmailform_log:name,email:*1
# UPDATE/INSERT
EMAIL_VAL,NAME_VAL; db; add:tt_address:email,name:email=EMAIL_VAL
# UPDATE
NAME_VAL; db; update:fe_users:name:uid=_FEUSER_UID
)
Default
dateMarkerFormat¶
General
dateMarkerFormat
Data type
string
Description
Date representation – see http://php.net/manual/en/function.strftime.php
Default
%Y-%m-%d
timeMarkerFormat¶
General
timeMarkerFormat
Data type
string
Description
Same as dateMarker
Default
%T
TS:¶
General
TS:
Data type
Data type:
Description
Description:
Default
Default:
fromName¶
General
fromName
Data type
String
Description
The name part of the “From:” header.
Default
fromMail¶
General
fromMail
Data type
String
Description
The email part of the “From:” header.
Default
overrideFromHeader¶
General
overrideFromHeader
Data type
Int
Description
0 = use self-defined “From:” header
1 = use user-defined “From:” header
Default
replyToName¶
General
replyToName
Data type
String
Description
The name part of the “Reply-To:” header.
Default
replyToMail¶
General
replyToMail
Data type
String
Description
The email part of the “Reply-To:” header.
Default
overrideReplyToHeader¶
General
overrideReplyToHeader
Data type
Int
Description
0 = use self-defined “Reply-To:” header
1 = use user-defined “Reply-To:” header
Default
overrideHeaderNameFormat¶
General
overrideHeaderNameFormat
Data type
Select
Description
If field ['text']['surname'] exists, set format of name override accordingly:
0 = “name surname”
1 = “surname, name”
Default
“name surname”
discloseRecipient¶
General
discloseRecipient
Data type
Check
Description
if checked, the “From:” and “Reply-To:” headers will be set to the first static or dynamic recipient.
Default
Unchecked
Cc¶
General
Cc
Data type
String
Description
Send mail as “Cc” to this/these email address(es). Each line is expected to be a valid email address.
Default
Bcc¶
General
Bcc
Data type
String
Description
Send mail as “Bcc” to this/these email address(es). Each line is expected to be a valid email address.
Default
contentTransferEncoding¶
General
contentTransferEncoding
Data type
Int
Description
0 = 8bit
1 = 7bit
2 = base64
3 = binary
4 = qouted-printable
Default
contentType¶
General
contentType
Data type
Int
Description
0 = text/plain
1 = text/html
Default
charset¶
General
charset
Data type
String
Description
Sets the Charset header parameter. Changing the Charset does NOT convert data to the Charset. (may come in the future)
Default
useMailer¶
General
useMailer
Data type
Int
Description
0 = “PHP mail()”
1 = “sendmail”
2 = “smtp”
-1 = “disable mail” (useful if you only want to store values)
Default
sendmailPath¶
General
sendmailPath
Data type
String
Description
The path to the sendmail executable.
Default
smtpHost¶
General
smtpHost
Data type
String
Description
The SMTP hostname to connect to.
Default
smtpPort¶
General
smtpPort
Data type
Int
Description
The SMTP port to connect to.
Default
smtpAuth¶
General
smtpAuth
Data type
int
Description
0 = No SMTP auth
1 = Use SMTP auth
Default
smtpUser¶
General
smtpUser
Data type
String
Description
The SMTP username
Default
smtpPasswd¶
General
smtpPasswd
Data type
String
Description
The SMTP password
Default
Known problems¶
None known in newest release :)
To-Do list¶
- Advanced email validation (validate address against mail server).
- Pagination support so that TMailform might be used for multi page questionnaires
- Captcha support
Changelog¶
Version 3.0.4
`IMPORTANT <http://bugs.typo3.org/view.php?id=3620>`_ Fixed security bug in included PHPMailer class which allowed remote command execution
Version 3.0.3
- Fixed bug http://bugs.typo3.org/view.php?id=4584
- Fixed bug
:underline:`http://bugs.typo3.org/view.php?id=4583
<http://bugs.typo3.org/view.php?id=4583>`_ . - Fixed bug http://bugs.typo3.org/view.php?id=4582.
- Fixed bug
:underline:`http://bugs.typo3.org/view.php?id=4522
<http://bugs.typo3.org/view.php?id=4522>`_ .
Version 3.0.2
Version 3.0.1
- Added option to disclose recipient email address in user copy mail ( http://bugs.typo3.org/view.php?id=3620). See documentation.
- Added possibility to use surname in mail headers (http://bugs.typo3.org/view.php?id=4153). See documentation.
- Fixed bug where user_copy field was always set (
:underline:`http://bugs.typo3.org/view.php?id=4152
<http://bugs.typo3.org/view.php?id=4152>`_ ). - Fixed bug where a semi colon in regex parameters broke validation (
:underline:`http://bugs.typo3.org/view.php?id=4291
<http://bugs.typo3.org/view.php?id=4291>`_ ). - Fixed bug causing a fatal error i some cases due to a invalid function call (http://bugs.typo3.org/view.php?id=4268).
- Added an auto generated marker for multi_recipient option text. See documentation.
- Added negation to regex in required values. See documentation.
- Added “notEquals” function for required values. See documentation.
- Added substitution of markers in user_copy subject.
- Added the possibility to disable sending mails – useful if you only want to store data. See documentation.
- Some minor refactoring.
Version 3.0.0
- WARNING: Configuration changed for field “default values”. See documentation for details.
- Made fe_user markers available for config field “Default values”. WARNING: marker format changed so the marker is prefixed with an underscore (eg. ###_FEUSER_USERNAME###). See documentation.
- Made it possible to load or store values in database. You really need to read the documentation! The code and concept is partly based on ideas and examples from Martin Kutschker – Thanks Martin.
- Added a preliminary logging facility using t3lib_div::sysLog()
- Added support for multiple languages. See documentation.
- Added options to change format of _DATE and _TIME markers. See documentation.
Version 2.0.5
Fixes bug causing the invalid email message to show when email is valid (###HEADER_EMAIL_INVALID### marker).
Version 2.0.4
- chechbox/radio field types are now validated as empty when not set.
- Minor bugfixes/tweaks
Version 2.0.3
- multi_recipient is now validated against required values.
- Disabled UTF-8 encoding detection as it seems to break some environments.
Version 2.0.2
- Fixed typo in code causing “Invalid argument supplied for foreach()...” error.
- Fixed typo in locallang.php file
Version 2.0.1
- Fixed incorrect “no template defined” error.
- Added utf-8 encoding detection of template file to avoid double encoding.
Version 2.0.0
- WARNING: The configuration of required fields has changed – See documentation.
- Changed field validation to make it more flexible using regular expressions, error message pr. field etc. See documentation.
- Added possibility to attach files to the mail.
- Added possibility to use TS/overwrite flexform values with TS. See pil_mailform/ext_conf_example.txt and TS reference in documentation.
- Fixed incorrect charset problem.
- Changed the way testmode shows data to mimic mail source.
Version 1.1.0
- WARNING: Changed subpart marker “###HEADER_MAIL_NOVALID###” to “###HEADER_MAIL_INVALID###” - as this is more correct English. Please remember to update your template!
- Most of the changes in this release are suggestions or issues reported by Martin Kutschker, who did an extensive review of TMailform. Thanks to Martin for taking the time to do this extensive review of TMailform and provide a German translation.
- Throw error if radio buttons and/or checkboxes are required and not set.
- Validate [email] field when the field has some value – even if the field is not required.
- Fixed issue with HTML linebreaks in text/plain emails.
- Added a flexform field for setting default values for fields in template.
- Added FE-user markers for eg. setting default [name] to “###FEUSER_USERNAME###” (Thanks to “pst”).
- Made extra markers available for mail body and subject. See the last part of the “Workflow” chapter of this manual.
- Made “<field>_VAL” markers available for “static subject” and “user subject prefix” flexform fields.
- Flexform field “Charset” now defaults to “$GLOBALS['TSFE']->metaCharset”.
- Utf8-encode template if “$GLOBALS['TSFE']->renderCharset” is utf-8 (Thanks to Vladimir I. Umnov).
- Added Russian translation (Thanks to Vladimir I. Umnov).
- Added German translation.
Version 1.0.1
Specified category in ext_emconf.php, so that TMailform is listed correctly in EM.
Version 1.0.0
- Realizing that 500+ people have downloaded TMailform and only a few bugs have been reported (and fixed), I have come to the conclusion that TMailform is ready to “become” stable. Thus, version is bumped to 1.0.0 – thanks to all that have send bug report and/or feature- request.
- Fixed email validation issue.
Version 0.2.2
Fixed required [text][email] issue.
Version 0.2.1
Fixed Charset bug.
Version 0.2.0
- Provided alternatives to PHP mail().
- Provided options for additional mail headers.
- Provide options for additional mail headers (Cc, Bcc, Content-Type, Charset,Content-Transfer-Encoding).
- Made it possible to have more than one static recipient.
- Added a field in configuration to prefix user subject.
- Made submitted values (###<field>_VAL###) available for TMAIL_THANKS and TMAIL_ERROR subparts.
- Update example template to new usage.
Version 0.1.3
Documentation updates
Version 0.1.2
- Fixed cache issue.
- Some refactoring. Fixes “wrong parameter count for array_keys()” issue.
Version 0.1.1
- Removed redundant and unnecessary files from extension.
- Fixed a few typos in documentation.
- Added missing screenshots to documentation.