manyMail

Overview

If you do a bit of web development you'll no doubt know you can use the mailto attribute in a hyperlink to bring up the e-mail client installed on the user's computer (if there is one).

This is great if you use Outlook or Thunderbird, but what if your e-mail is web based like Gmail or Hotmail? Yup, you're a bit stumped. This is where manyMail comes in; it provides an interactive user interface for sending e-mails from your website. *

OK, with the preamble out of the way, how about a quick demo?

e-mail player xyz

$(document).ready(function() {
$("#simple-example").manyMail();
});

Simple demo

Notice you can drag an e-mail between the To:, Cc: and Bcc: tabs. The end-user can also remove any e-mail addresses they don't want to send (more useful on say a team based website ).

Now we've got an idea of what we're looking at, let's look a bit deeper.

Dependencies

manyMail uses the jQuery javascript framework to provide the functionality of the plug-in, as well as the jQuery UI dialog and jQuery UI tabs to provide the pop-up for changing the e-mail properties.

As such you will need to have the jQuery and the jQuery UI javascript frameworks downloaded as well as the manyMail plug-in. You will also need a ui theme, we're using the ui-darkess theme here as it fits nicely with the toepoke design.

Note that manyMail only uses the dialog and tabs parts of the jQuery UI framework, so you can just download those components if you wish.

Settings

As with many plug-ins, manyMail has a few default properties you can override to change its behaviour.

The following properties are used to change how the dialog control behaves.

1. height
2. width
3. title
4. modal

We won't go over those properties as the jQuery documentation already does an excellent job, the important part is that those properties are honoured. However a little example might be useful.

e-mail player1

$("#jquery-properties-example").manyMail({
title: "this is a new title",
width: screen.width * 0.66,
height: screen.height * 0.66,
modal: false
});

jQuery Properties Demo

Here we've given our own title for the dialog, changed the dialog size to roughly ⅔ of the available screen space and the dialog is no longer modal.

The only other property is the separator which specifies what character is used to delimit the e-mail addresses in the href attribute. By default this is a semi-colon (;) and this is fine for 99% of the time.

Override Methods

As well as the various properties that can be modified, we can also change how the plug-in functions, by overriding a variety of exposed methods, as detailed below.

decode

You may notice that all the samples use invalid e-mail addresses, such as someone[at]example.com. This is on purpose and is a primitive anti e-mail harvesting technique (as this page can be viewed by anonymous users).

Of course before we can send an e-mail we need to convert the address into the correct format. We can do this either on the server-side, or on the client-side, which is where the decode event comes in.

When the plug-in extracts the e-mail addresses from the href in your mailto link, it calls the decode method which can be overridden, as illustrated below:

Decode demo

$("#decode-example").manyMail({
decode: function(emailAddress) {
// Simple example of decoding an e-mail address for the dialog.
// Rendered on the page as "player1[at]example.com", this replaces 
while (emailAddress.indexOf("[at]") != -1)
emailAddress = emailAddress.replace("[at]", "@");

return emailAddress;
}			
});

Decode demo

In this example we've just replaced the [at] with the appropriate ampersand (&). Naturally you're free to use whatever anti-harvesting method you like, just override the decode method to arrange the data as you need. Alternatively you can always do the decoding server-side when you send the message.

loadAddresses

Perhaps you want to add an additional address, perhaps so you get a copy of the e-mail being sent (though we'd suggest doing this server-side).

Add addresses callback demo

$("#loadAddresses-example").manyMail({
loadAddresses: function(email) {
email.To += ";another.to[at]example.com";
email.Cc = "another.cc[at]example.com";
email.Bcc = "another.bcc[at]example.com";
}
});

Notice in the loadAddresses override above the += part and the semi-colon (;), this is to preserve anything that's already in the To: part of the mailto reference.

Add Addresses Demo

The further thought is we can use this function to populate the pop-up form, rather than use the normal href method, as in this example:

	Add e-mails at runtime

$("#loadAddresses-without-href-example").manyMail({
loadAddresses: function(email) {
email.To = "to-someone[at]example.com";
email.Cc = "cc-someone[at]example.com";
email.Bcc = "bcc-someone[at]example.com";
}
});

Add e-mails at runtime

Naturally the further thought would be to use the above method to load your e-mail addresses from the server using an Ajax call, this would further mitigate the risk of a spambot picking up your users e-mail addresses.

The downside with this approach however, is you lose the in-built progessive goodness when using the mailto attribute (as there's no address in the mailto attribute of the href). That said there's no reason why you couldn't still specify a mailto attribute with no e-mail addresses defined, as in:

	Add e-mails at runtime with no e-mail addresses

$("#loadAddresses-without-href-example-with-no-to-address").manyMail({
loadAddresses: function(email) {
email.To = "to-someone[at]example.com";
email.Cc = "cc-someone[at]example.com";
email.Bcc = "bcc-someone[at]example.com";
}
});				

Add e-mails at runtime with no e-mail addresses

Note the & at the front tells the browser there is no To addresses associated with this hyperlink.

validate

When clicking the send button on the form the validate method is called so any errors on the form can be trapped and displayed. The method performs the following checks:

1. There is at least one address in the To: tab.
2. There is a subject defined.
3. There is some content in the body

Should any required data be missing the defaultValidator will return an error message, which is then displayed to the user. If you just click the send button in the demo you should see the default error message.

	Default validation demo

$("#default-validator-example").manyMail();

Default validation demo

As with other of the plug-in functions, the validate method can be overridden. If you wish to override valdiate method, return an empty string to indicate everything is OK, otherwise return a set of LI tags, one for each error message to display.

$("#override-validator-example").manyMail({
validate: function(email) {
if (email.To == null || email.To == "") {
// mmm, no to address, who we going to send to?
return "
The overridden validate message says to need a To!
";
}
// our overridden rules have passed, so let them through
return "";
}
});

Override validation demo

Buttons

You may not want all the buttons in the dialog displayed. Perhaps for aesthetic reasons or you think your users may be insulted by being offered "Help" on filling in an e-mail form .

Whatever the reason, it's quite straightforward to disable the buttons, except the Send button naturally!

	Buttons demo

$("#buttons-example").manyMail({
showHelp: false,
showReset: false,
showClient: false
});

Buttons demo

Confirmation

The confirmation method can be used as a final erm ... confirmation that the user wants to send the e-mail. This is a simple function that expects a true or false value to be returned. By default the function returns true and no confirmation message is displayed, so you only need to override this method if you want a confirmation message.

	Confirmation demo

$("#confirmation-example").manyMail({
confirmation: function(email) {
return 
confirm("Are you sure you want to send this communication?");
}
});

Confirmation demo

Send

Finally there is the send method which must be overridden as this method calls your server with the content to e-mail.

	Send demo

$("#send-example").manyMail({
send: function(email) {

// add a little helper method for showing what will be sent
email.formatList = function(listType, emailList) {
if (emailList == null)
return "";
var msg = listType + ":\n";
for (var index in emailList) {
msg += emailList[index] + "\n";
}
msg += "\n\n";
return msg;
};

var msg = "Subject: " + email.Subject + "\n";
msg += email.formatList("To", email.ToList);
msg += email.formatList("Cc", email.CcList);
msg += email.formatList("Bcc", email.BccList);
msg += "Body:\n\n" + email.Body;

// ToDo: Place your Ajax call to the server here
alert(msg);
}
});

Send demo

Email Object

You may have noticed through each of the methods outlined above, each has an email parameter detailing the various properties of the email dialog, so let's have a look at what's exposed.

Additional Server-side checks

Hopefully an underlying theme of this article has been the dangerous territory we place ourselves in if we expose the e-mail addresses of our users in plain view on a website.

We wholeheartedly recommend only using the plug-in behind a page with some form of authentication or an alternative method of ensuring the website is being displayed to a real person, such as recaptcha, before showing the e-mail addresses (note having the email addresses hard-coded in a javascript function is as dangerous as through HTML).

To summarise then, we hope you find the plug-in useful although keep in mind a few points.

1. Don't show e-mail addresses in plain-view (otherwise they will get harvested by the bots).
2. If you can, only trust your back-end database for setting the Reply-To and From e-mail fields. Otherwise your site could become a target for being used a spamming tool.
3. Ideally only allow e-mailing from authenticated users. At the very least use something like a recaptcha before showing the e-mail addresses of your users.

All that said, we hope you find the plug-in useful.

Source

Source available on github.

Footnotes

If you're after a more traditional contact form, this looks like a good one.

Posted in : css, development, fluqi, jquery-ui, techie-stuff