EXT: TMailform¶

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:

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.

Method¶

notEmpty¶

regex:/[0-9]/; text: Need an integer

regex:!/[0-9]/; text: Please any remove integers

lang¶

notEquals¶

lang¶

inList¶

lang¶

regex¶

lang¶

Method¶

plain¶

mark¶

db¶

Method¶

db¶

NAME_VAL; db; new:tx_pilmailform_log:name:*1
EMAIL_VAL; db; new:tx_pilmailform_log:email:*1

NAME_VAL,EMAIL_VAL; db; new:tx_pilmailform_log:name,email:*1

new¶

add¶

update¶

FField:¶

Testmode¶

Static subject¶

Subject user override¶

User subject prefix¶

Use recipient¶

Static recipient(s)¶

Dynamic recipient¶

Copy to user¶

User copy subject¶

Template¶

Multiple language support¶

Locallang file¶

Field:¶

Replace error markers with¶

Required Values¶

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

Default values¶

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

Store values¶

# 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

Date marker format¶

Time marker format¶

Field:¶

“From” name¶

“From” email¶

“From” header user override¶

“Reply-To” name¶

“Reply-To” email¶

“Reply-To” header user override¶

Header name override format¶

Disclose recipient email in user copy¶

“Cc” addresses¶

“Bcc” addresses¶

Content-Transfer-Encoding¶

Content-Type¶

Charset¶

Send mail using¶

Path to sendmail¶

SMTP host¶

SMTP port¶

Use SMTP authentication¶

SMTP username¶

SMTP password¶

TS¶

testmode¶

staticSubject¶

overrideSubject¶

userSubjectPrefix¶

typeofRecipient¶

staticRecipient¶

plugin.tx_pilmailform_pi1.staticRecipient (
    user@mail.domain.tld
)

dynamicRecipient¶

plugin.tx_pilmailform_pi1.dynamicRecipient (
    Please select recipient
    user@mail.domain.tld
    user@mail.domain.tld
)

copyToUser¶

userCopySubject¶

template¶

useLL¶

LLFile¶

TS:¶

errorSubstitution¶

requiredValues¶

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
)

defaultValues¶

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=
)

storeValues¶

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
)

dateMarkerFormat¶

timeMarkerFormat¶

TS:¶

fromName¶

fromMail¶

overrideFromHeader¶

replyToName¶

replyToMail¶

overrideReplyToHeader¶

overrideHeaderNameFormat¶

discloseRecipient¶

Cc¶

Bcc¶

contentTransferEncoding¶

contentType¶

charset¶

useMailer¶

sendmailPath¶

smtpHost¶

smtpPort¶

smtpAuth¶

smtpUser¶

smtpPasswd¶