.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt .. role:: underline ============== 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: EXT: TMailform ============== Extension Key: **pil\_mailform** Copyright 2007, Sebastian Busch Copyright 2005-2007, 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: 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: Introduction ------------ .. _What-does-it-do: 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: Screenshots ^^^^^^^^^^^ |img-1| 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: 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[][]”, where corresponds to the form field type and is the fields name identifier. In example, this would be a correct form field: :: The , 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 “###\_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: 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: 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: :: ###SUBJECT_ERR_TXT### ###NAME_ERR_TXT### ###EMAIL_ERR_TXT### Similar we can add the message from the user as a textarea field type: :: ###MESSAGE_ERR_TXT### 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: :: ###USER_TYPE_ERR_TXT### Private
Buisness 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 “###\_\_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: :: ###LEVEL_ERR_TXT### 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. :: ###JOBDESCRIPTION_ERR_TXT### 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/: :: ###FILE1_ERR_TXT### ###FILE2_ERR_TXT### 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: 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: 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: 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: 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 “;” 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 “”. .. _Field-user-copy: 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: 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: 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: 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\_###”, where is an languageKey index from your locallang xml file. It is as simple as that :) .. _Working-with-fields-and-values: 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: :: :,...,;...; :,..., Note: Invalid queries are logged using t3lib\_div::sysLog and you can set the behavior of sysLog using Install Tool. .. _Field-value-parser-reference: Field/value parser reference ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. ### BEGIN~OF~TABLE ### .. _Method: Method """""" .. container:: table-row Required values Method Parameters Parameters Processor Processor Parameters-2 Parameters Notes Notes .. _notEmpty: notEmpty """""""" .. container:: table-row 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: lang """" .. container:: table-row Required values lang Parameters lang key .. _notEquals: notEquals """"""""" .. container:: table-row 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: lang """" .. container:: table-row Required values lang Parameters lang key .. _inList: inList """""" .. container:: table-row Required values inList Parameters Comma separated list of values (item1,item2,...,itemN) Processor text Parameters-2 string .. _lang: lang """" .. container:: table-row Required values lang Parameters lang key .. _regex: regex """"" .. container:: table-row Required values regex Parameters Regular expression (perl compatible). Processor text Parameters-2 string .. _lang: lang """" .. container:: table-row Required values lang Parameters lang key .. _Method: Method """""" .. container:: table-row Required values Method Parameters Parameters Processor Processor Parameters-2 Parameters Notes Notes .. _plain: plain """"" .. container:: table-row 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: mark """" .. container:: table-row Required values mark Parameters predefined marker Processor Any predefined marker. Example: \_FEUSER\_USERNAME .. _db: db "" .. container:: table-row Required values db Parameters None Processor get Parameters-2 table:field[,field]:where clause Notes See “Store values” section of this table. .. _Method: Method """""" .. container:: table-row Required values Method Parameters Parameters Processor Processor Parameters-2 Parameters Notes Notes .. _db: db "" .. container:: table-row 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: new """ .. container:: table-row Required values new Parameters table:field[,field]:unique identifier .. _add: add """ .. container:: table-row Required values add Parameters table:field[,field]:where clause .. _update: update """""" .. container:: table-row Required values update Parameters table:field[,field]:where clause .. ###### END~OF~TABLE ###### .. _Flexform-reference: Flexform reference ^^^^^^^^^^^^^^^^^^ .. ### BEGIN~OF~TABLE ### .. _FField: FField: """"""" .. container:: table-row General FField: Data type Data type: Description Description: Default Default: .. _Testmode: Testmode """""""" .. container:: table-row 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: Static subject """""""""""""" .. container:: table-row 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: Subject user override """"""""""""""""""""" .. container:: table-row 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: User subject prefix """"""""""""""""""" .. container:: table-row 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: Use recipient """"""""""""" .. container:: table-row General Use recipient Data type Select Description Use either static recipient(s) or dynamic recipient of the mail Default “static recipient” .. _Static-recipient-s: Static recipient(s) """"""""""""""""""" .. container:: table-row 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: Dynamic recipient """"""""""""""""" .. container:: table-row General Dynamic recipient Data type String Description A recipient is defined by “;”. Any line not containing a semicolon, is treated as a “string only” option in the select box. Default Empty string .. _Copy-to-user: Copy to user """""""""""" .. container:: table-row 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: User copy subject """"""""""""""""" .. container:: table-row 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: Template """""""" .. container:: table-row General Template Data type String Description Path to template file Default Empty string .. _Multiple-language-support: Multiple language support """"""""""""""""""""""""" .. container:: table-row General Multiple language support Data type Check Description Check this to enable multiple language support. Requires a locallang file. Default .. _Locallang-file: Locallang file """""""""""""" .. container:: table-row General Locallang file Data type String Description Path to locallang file Default .. _Field: Field: """""" .. container:: table-row General Field: Data type Data type: Description Description: Default Default: .. _Replace-error-markers-with: Replace error markers with """""""""""""""""""""""""" .. container:: table-row General Replace error markers with Data type String Description Any ###\_ERR### markers will be replaced with this string. Default Empty string .. _Required-Values: Required Values """"""""""""""" .. container:: table-row 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 ###\_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: Default values """""""""""""" .. container:: table-row 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: Store values """""""""""" .. container:: table-row 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: Date marker format """""""""""""""""" .. container:: table-row 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: Time marker format """""""""""""""""" .. container:: table-row General Time marker format Data type String Description Same as dateMarker Default %T .. _Field: Field: """""" .. container:: table-row General Field: Data type Data type: Description Description: Default Default: .. _From-name: “From” name """"""""""" .. container:: table-row General “From” name Data type String Description The name part of the “From:” header. Default Empty string .. _From-email: “From” email """""""""""" .. container:: table-row General “From” email Data type String Description The email part of the “From:” header. Default Empty string .. _From-header-user-override: “From” header user override """"""""""""""""""""""""""" .. container:: table-row 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: “Reply-To” name """"""""""""""" .. container:: table-row General “Reply-To” name Data type String Description The name part of the “Reply-To:” header. Default Empty string .. _Reply-To-email: “Reply-To” email """""""""""""""" .. container:: table-row General “Reply-To” email Data type String Description The email part of the “Reply-To:” header. Default Empty string .. _Reply-To-header-user-override: “Reply-To” header user override """"""""""""""""""""""""""""""" .. container:: table-row 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: Header name override format """"""""""""""""""""""""""" .. container:: table-row 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: Disclose recipient email in user copy """"""""""""""""""""""""""""""""""""" .. container:: table-row 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: “Cc” addresses """""""""""""" .. container:: table-row 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: “Bcc” addresses """"""""""""""" .. container:: table-row 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: Content-Transfer-Encoding """"""""""""""""""""""""" .. container:: table-row General Content-Transfer-Encoding Data type Select Description Set the mails “Content-Transfer-Encoding” header. Default “8bit” .. _Content-Type: Content-Type """""""""""" .. container:: table-row 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: Charset """"""" .. container:: table-row General Charset Data type String Description Sets the Charset header parameter. Default $GLOBALS['TSFE']->renderCharset .. _Send-mail-using: Send mail using """"""""""""""" .. container:: table-row 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: Path to sendmail """""""""""""""" .. container:: table-row General Path to sendmail Data type String Description The path to the sendmail executable. Default “/usr/sbin/sendmail” .. _SMTP-host: SMTP host """"""""" .. container:: table-row General SMTP host Data type String Description The SMTP hostname to connect to. Default “localhost” .. _SMTP-port: SMTP port """"""""" .. container:: table-row General SMTP port Data type Integer Description The SMTP port to connect to. Default 25 .. _Use-SMTP-authentication: Use SMTP authentication """"""""""""""""""""""" .. container:: table-row 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: SMTP username """"""""""""" .. container:: table-row General SMTP username Data type String Description The SMTP username Default Empty string .. _SMTP-password: SMTP password """"""""""""" .. container:: table-row General SMTP password Data type String Description The SMTP password Default Empty string .. ###### END~OF~TABLE ###### .. _TypoScript-reference: TypoScript reference ^^^^^^^^^^^^^^^^^^^^ Note: The TS values will overwrite flexform values. .. ### BEGIN~OF~TABLE ### .. _TS: TS "" .. container:: table-row General TS Data type Data type: Description Description: Default Default: .. _testmode: testmode """""""" .. container:: table-row 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: staticSubject """"""""""""" .. container:: table-row General staticSubject Data type String Description Defines a static subject for the mails. You can use markers in this field. Default .. _overrideSubject: overrideSubject """"""""""""""" .. container:: table-row General overrideSubject Data type Int Description If set to 1, the static subject will be overridden by field ['text']['subject'] Default .. _userSubjectPrefix: userSubjectPrefix """"""""""""""""" .. container:: table-row 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: typeofRecipient """"""""""""""" .. container:: table-row General typeofRecipient Data type Int Description 0 = static recipient(s) 1 = dynamic recipient Default .. _staticRecipient: staticRecipient """"""""""""""" .. container:: table-row 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: dynamicRecipient """""""""""""""" .. container:: table-row General dynamicRecipient Data type String Description A recipient is defined by “;”. 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: copyToUser """""""""" .. container:: table-row 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: userCopySubject """"""""""""""" .. container:: table-row 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: template """""""" .. container:: table-row General template Data type String Description Path to template file Default .. _useLL: useLL """"" .. container:: table-row General useLL Data type Int Description 0 = enable multiple languages 1 = disable multiple languages Default .. _LLFile: LLFile """""" .. container:: table-row General LLFile Data type String Description Path to locallang file Default .. _TS: TS: """ .. container:: table-row General TS: Data type Data type: Description Description: Default Default: .. _errorSubstitution: errorSubstitution """"""""""""""""" .. container:: table-row General errorSubstitution Data type String Description Any ###\*\_ERR### markers will be replaced with this string. Default .. _requiredValues: requiredValues """""""""""""" .. container:: table-row 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 ###\_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: defaultValues """"""""""""" .. container:: table-row 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: storeValues """"""""""" .. container:: table-row 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: dateMarkerFormat """""""""""""""" .. container:: table-row General dateMarkerFormat Data type string Description Date representation – see http://php.net/manual/en/function.strftime.php Default %Y-%m-%d .. _timeMarkerFormat: timeMarkerFormat """""""""""""""" .. container:: table-row General timeMarkerFormat Data type string Description Same as dateMarker Default %T .. _TS: TS: """ .. container:: table-row General TS: Data type Data type: Description Description: Default Default: .. _fromName: fromName """""""" .. container:: table-row General fromName Data type String Description The name part of the “From:” header. Default .. _fromMail: fromMail """""""" .. container:: table-row General fromMail Data type String Description The email part of the “From:” header. Default .. _overrideFromHeader: overrideFromHeader """""""""""""""""" .. container:: table-row General overrideFromHeader Data type Int Description 0 = use self-defined “From:” header 1 = use user-defined “From:” header Default .. _replyToName: replyToName """"""""""" .. container:: table-row General replyToName Data type String Description The name part of the “Reply-To:” header. Default .. _replyToMail: replyToMail """"""""""" .. container:: table-row General replyToMail Data type String Description The email part of the “Reply-To:” header. Default .. _overrideReplyToHeader: overrideReplyToHeader """"""""""""""""""""" .. container:: table-row General overrideReplyToHeader Data type Int Description 0 = use self-defined “Reply-To:” header 1 = use user-defined “Reply-To:” header Default .. _overrideHeaderNameFormat: overrideHeaderNameFormat """""""""""""""""""""""" .. container:: table-row 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: discloseRecipient """"""""""""""""" .. container:: table-row 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: Cc "" .. container:: table-row 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: Bcc """ .. container:: table-row 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: contentTransferEncoding """"""""""""""""""""""" .. container:: table-row General contentTransferEncoding Data type Int Description 0 = 8bit 1 = 7bit 2 = base64 3 = binary 4 = qouted-printable Default .. _contentType: contentType """"""""""" .. container:: table-row General contentType Data type Int Description 0 = text/plain 1 = text/html Default .. _charset: charset """"""" .. container:: table-row 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: useMailer """"""""" .. container:: table-row 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: sendmailPath """""""""""" .. container:: table-row General sendmailPath Data type String Description The path to the sendmail executable. Default .. _smtpHost: smtpHost """""""" .. container:: table-row General smtpHost Data type String Description The SMTP hostname to connect to. Default .. _smtpPort: smtpPort """""""" .. container:: table-row General smtpPort Data type Int Description The SMTP port to connect to. Default .. _smtpAuth: smtpAuth """""""" .. container:: table-row General smtpAuth Data type int Description 0 = No SMTP auth 1 = Use SMTP auth Default .. _smtpUser: smtpUser """""""" .. container:: table-row General smtpUser Data type String Description The SMTP username Default .. _smtpPasswd: smtpPasswd """""""""" .. container:: table-row General smtpPasswd Data type String Description The SMTP password Default .. ###### END~OF~TABLE ###### .. _Known-problems: Known problems -------------- None known in newest release :) .. _To-Do-list: 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: Changelog --------- **Version 3.0.4** **`IMPORTANT `_** `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` `_ `. `_ - `Fixed bug http://bugs.typo3.org/view.php?id=4582. `_ - `Fixed bug `_ `:underline:`http://bugs.typo3.org/view.php?id=4522` `_ `. `_ **Version 3.0.2** `Re-enabled parsing default values by url/pivars (Thanks to Florian for pointing out its dissapearance). `_ **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` `_ `). `_ - `Fixed bug where a semi colon in regex parameters broke validation ( `_ `:underline:`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 “\_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 (###\_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. .. ######CUTTER_MARK_IMAGES###### .. |img-1| image:: img-1.png .. :align: left .. :border: 0 .. :height: 255 .. :id: Graphic2 .. :name: Graphic2 .. :width: 260