Tips & Tricks for TYPO3 Extension Powermail

When it comes to complex web forms the onboard TYPO3 content element “Mail form” soon reaches its limits. The well known extension Powermail will fill the gap. Here are some tips and tricks that might come in handy if you start using it.

These tips apply to Powermail versions starting with 1.6. Older versions differ considerably! Install the extension and take the first steps along the manual.

Don’t forget to add Powermail’s static template to your template record. For a first trial I also recommend to add one of the two CSS templates (“fancy” for modern eye candy, “basic” for the more conservative mind).

JavaScript framework conflicts

Since version 1.6.0 Powermail uses the jQuery JavaScript framework instead of Prototype. Make sure your existing website does not use Prototype for any other purposes as it will conflict with jQuery. If you are using the wide spread Perfect Lightbox extension, make sure you set it up to use jQuery too:

#TS Constants
plugin.perfectlightbox.libraryToUse = jquery

You should definitely check the resulting HTML code of your website to make sure that the busy zoo of extensions in your TYPO3 system does not try to install jQuery multiple times. To do that search the code for all script tags and check what they load.

For my own projects I never rely on any of the built in jQuery versions that come with many extensions. I switch them all off and include the latest jQuery version myself. You can painlessly load it from the Google libraries API using the following TypoScript:

# TS Setup
page.headerData.10 = TEXT
page.headerData.10.value (
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js" type="text/JavaScript"></script>
)

Multiple script lines can be included between the brackets if you need to add more header lines to load additional JS or CSS files.

To prevent Powermail from loading its own jQuery library use:

# TS Setup
page.includeJSFooterlibs.powermail_jQuery >

And while we are at it…
to prevent Perfect Lightbox from loading its own jQuery library use:

# TS Constants
plugin.perfectlightbox.includeJSLibrarys = 0

Forms with Powermail

After you have managed all the JavaScript hassles you are finally ready to create your first form. Its easy and comfortable – have a look at the manual! The form will usually look nice and clean in the website and will show as a simple list of fieldnames and values in the email that is sent to you (the website owner) and in second email (optional) that is sent as a copy to the visitor of your website who filled in and sent the form. So far so good – if this is what you need, you are done.

But Powermail allows you to apply extreme formating to both the form in the website as well as the emails that are sent out on submission of the form! Have a look:

Formatting the website form

This is done using CSS rules. Create a copy of the basic or the fancy CSS file that comes with Powermail (see folder EXT:powermail/res/css/) and modify it to your needs. You can include your new CSS file into your HTML header with the headerData property shown above. Don’t forget to remove the static CSS file that we added to your template at the very beginning of this text!

To the right you find an example of a web form that has been formated to mimic its paper counterpart (click to enlarge).

And below is a part of the CSS code that has been used to create that look:

fieldset.tx-powermail-pi1_fieldset .tx_powermail_pi1_fieldwrap_html > label {
	/* label */
	display: block;
	position: relative;
	top: 40px; left: 0px;
	clear: left;
	font-size: 10px;
	font-weight: bold;
	color: #666;
}
div.tx_powermail_pi1_fieldwrap_html {
	/* DIV container arround every field */
	float: left;
	margin: 0 0 1.0em 0;
}
#my_form #powermaildiv_uid01 input{}			/* Name */
#my_form #powermaildiv_uid02 input{ margin-right: 30px; } /* Vorname */
#my_form #powermaildiv_uid03 input{ margin-right: 160px; } /* Geboren */
#my_form #powermaildiv_uid04 input{ width: 260px; }	/* Strasse */
#my_form #powermaildiv_uid05 input{ width:  60px; margin-right: 30px; }	/* Hausnr. */
#my_form #powermaildiv_uid06 input{ }  			/* Familienstand */
#my_form #powermaildiv_uid07 input{ }			/* Nationalität */

Formatting the emails that are sent on submission

This is done by providing an HTML template with placeholders right in the Powermail plugin instance of your web page (in TYPO3 backend):

Go to the  Recipients  tab and replace the default content  ###POWERMAIL_ALL###  with some HTML code that contains placeholders for your fields (e.g . ###UID01###  to insert the content of your very first form field). I recommend using the code view of the RTE to have full control over the HTML code. Make sure that you restrict yourself to very simple HTML, as email clients usually only implement a small sub-set of HTML and you normally will not know which clients will be used by the recipients of your emails. For complex email designs don’t hesitate to use invisible tables to structure the content. Although this is last millennium’s technology, it is still the most secure method to ensure that all email clients display your content correctly.

To the right you see an example of how my web form will look when received by email (click to enlarge).
And below is a part of the HTML template code that was used to create that look:

<div style="background-color: #eeeeee; width:695px; padding:20px;">
  <table border="0" cellspacing="0" cellpadding="0" style="margin: 10px 0px;">
    <tbody>
      <tr>
        <td width="150" style="border-bottom: 1px solid black; background-color: #ffffff; padding: 2px 0px;">###UID01###&nbsp;</td>
        <td width="10"  >&nbsp;</td>
        <td width="150" style="border-bottom: 1px solid black; background-color: #ffffff; padding: 2px 0px;">###UID02###&nbsp;</td>
        <td width="35"  >&nbsp;</td>
        <td width="150" style="border-bottom: 1px solid black; background-color: #ffffff; padding: 2px 0px;">###UID03###&nbsp;</td>
        <td width="10"  >&nbsp;</td>
        <td width="150" >&nbsp;</td>
      </tr>
      <tr>
        <td style="font-size: 70%; font-weight: bold;">(Name)</td>
        <td>&nbsp;</td>
        <td style="font-size: 70%; font-weight: bold;">(Vorname)</td>
        <td>&nbsp;</td>
        <td style="font-size: 70%; font-weight: bold;">(Geburtsdatum)</td>
        <td>&nbsp;</td>
        <td>&nbsp;</td>
      </tr>
    </tbody>
  </table>
  <table border="0" cellspacing="0" cellpadding="0" style="margin: 10px 0px;">
    <tbody>
      <tr>
        <td width="250" style="border-bottom: 1px solid black; background-color: #ffffff; padding: 2px 0px;">###UID04###&nbsp;</td>
        <td width="10"  >&nbsp;</td>
        <td width="50"  style="border-bottom: 1px solid black; background-color: #ffffff; padding: 2px 0px;">###UID05###&nbsp;</td>
        <td width="35"  >&nbsp;</td>
        <td width="150" style="border-bottom: 1px solid black; background-color: #ffffff; padding: 2px 0px;">###UID06###&nbsp;</td>
        <td width="10"  >&nbsp;</td>
        <td width="150" style="border-bottom: 1px solid black; background-color: #ffffff; padding: 2px 0px;">###UID07###&nbsp;</td>
      </tr>
      <tr>
        <td style="font-size: 70%; font-weight: bold;">(Straße)</td>
        <td>&nbsp;</td>
        <td style="font-size: 70%; font-weight: bold;">(Nr.)</td>
        <td>&nbsp;</td>
        <td style="font-size: 70%; font-weight: bold;">(Familienstand)</td>
        <td>&nbsp;</td>
        <td style="font-size: 70%; font-weight: bold;">(Nationalität)</td>
      </tr>
    </tbody>
  </table>

  ...

</div>

If you want to send an identically formatted email to your sender (the person filling the form in your website) you do not have to copy the whole HTML template code into the Sender  tab of your plugin instance. Instead simply use the placeholder  ###POWERMAIL_EMAILRECIPIENT_RTE###  there. It will do the job for you!

Formatting dates

You will find that fields that are set to the date type display a nicely formatted date (according to TYPO3′s locale settings) in your webpage, but show up in the form YYYY-MM-DD in the incoming emails. To correct this use the following code (adapt the formatting rules according to PHP’s strftime syntax):

# TS Constants
plugin.powermail {
	format.datetime = %m/%d/%Y %I:%M %P
	format.date = %m/%d/%Y
}

Set the plain text name of the sender(s)

Both the emails that go to the sender (website visitor) and the recipient (website owner) have different  From  (= sender email address) attributes. This makes sense. The wired thing is that you define the From-address for the sender’s email in the  Recipients  tab and the From-address for the recipient’s email in the  Sender  tab. Well, the logic is probably that this way they can respond to each other.

Anyway, you might find that you can easily define the plain text name in the  Sender  tab –it’s called  Senders name  and you can assign multiple form fields to it that will be concatenated.

But you will probably have problems to define the plain text name in the  Recipients  tab. You have to enter it as a first line in the field  Email of Recipient (and Name of Recipient),  followed by all email addresses of all recipients (line by line). If you do not enter a plain text name in the first line (starting with an email address right away) your visitors will receive email addresses with the plain text name “powermail” which is not very commendable.

Calculating field content with Javascript

With complex forms you will soon want to calculate some field entries using Javascript. Doing a Google search you will probably find many tips to use the additional extension  powermail_cond  for that purpose. Unfortunately the latest versions of that extension do not offer the option [manualEventHandler] any more, which is needed to add your own JavaScript handlers to the Powermail form fields. You can fall back to the outdated extension fork  powermail_cond_jquery  which still has that option, but I won’t recommend that as that fork will probably not be maintained any more. Instead there is a much simpler solution:

As jQuery is already part of your installation, you can create the needed Javascript to calculate field content and attach event handlers to the Powermail fields with minimal effort, using the TYPO3 content element “Plain HTML”. Add such an element after your Powermail element and enter the needed Javascript code.

[UPDATE 20120511]:  ATTENTION! Do NOT use a Powermail field with field type set to HTML! As multiple comments to this post have shown, Powermail destroys script blocks within such HTML fields. Instead use an independent TYPO3 content element AFTER the Powermail plugin element in your page and set the type of this independent element to “Plain HTML”.

Here are some script examples to fill into the HTML element (don’t forget to adapt to your UIDs!):

Check/uncheck a checkbox if a text input field is filled/emptied

<script type="text/javascript">
/*<![CDATA[*/
  var checkboxID  = "#uid10_3";
  var textfieldID = "#uid20";
  $(textfieldID).change(function(){
    $("checkboxID").prop("checked", $(textfieldID).val().trim()!="");
    // FOR JQUERY < 1.6:  use attr() instead of prop() !!!
  })
/*]]>*/
</script>

ATTENTION:
This is jQuery >= 1.6 code. If you are using older versions you will have to replace the prop() function by the attr() function!

Fill a field with the product of two other fields (C=A*B)

<script type="text/javascript">
/*<![CDATA[*/
  var param1ID = "#uid30";
  var param2ID = "#uid31";
  var resultID = "#uid40";

  // attach change events to parameter fields
  $(param1ID).change(updateResult);
  $(param2ID).change(updateResult);

  function updateResult(){
    $(resultID).val($(param1ID).val()*$(param2ID).val());
  }
/*]]>*/
</script>

Quick hint for powermail_cond users

If you still want to give powermail_cond a try (it can basically switch the visibility of fields and the available options of select boxes, depending on the content of other fields), you may find yourself wondering how to create the rules that are described in the manual. I searched my ass off to find it.

Solution: Use the list module to create new rules records in the page where your Powermail plugin is used. But don’t use the list module to create new conditions records – this is done from within the rules!

Avoiding spam

Last but not least – some remarks about security:

As mentioned in the Powermail manual, it is very advisable to install the extension wt_spamshield which implements a strong multi-layered spam protection that is invisible to the user and requires only minimal configuration effort.

If you don’t do it you risk that your forms are used to send out all kind of spam links!

It can be done by simply entering a faked sender email address and using any of the textarea fields to transport links of a nice bunch of websites that you never wanted to be associated with. If you set up your form to send a copy to the visitor of your website, it can be used with a faked sender address to send to ANYBODY! And the emails will name you as the origin of this trash.

To avoid that risk:

Simply install the extension wt_spamshield, add the static template and add this line of TypoScript:

#TS Setup:
plugin.wt_spamshield.enable.powermail = 1

You can tell that the spamshield if active by looking at the HTML code of your form’s page. You should find a new input field at the very end of the form that has a class attribute  class=”tx_powermail_pi1_tastyhoney”  attached. This is the honey pot field that is part of one of the layers of spam protection.