Archive for 'guardMailto'

using guardMailto

Friday, 14 July 2006

Introduction

guardMailto is a lightweight unobtrusive JavaScript library to make it more difficult for spammers to extract email addresses from web sites.

You don’t need to be a JavaScript expert to use it. On the other hand, it has some options intended for use by people who are comfortable programming JavaScript. My hope is that you’ll find it useful if you’ve never used JavaScript in a web page before, and even more useful if you’re a guru.

(This is the short version. introducing guardMailto is an article that discusses the design approach behind this library in more detail.)

Adding guardMailto to Your Site

You can download either the raw javascript guardMailto.js or a gzip archive guardMailto.js.gz.

Just include guardMailto.js in the <head> section of your pages:

<script type="text/javascript" src="guardMailto.js></script>

There is one function, mwmw.guardMailto(). It has 3 required arguments (and some options).

  1. “linkElement” can be either the id of the element (as a string) or an HTML Element Node
  2. “userName” is the part of the email address preceding the @ character:
    test@example.com
  3. “domain” is the part of the email address between the @ character and the top level domain (.com, .org, .net, etc.):
    test@example.com

You need a way to identify each place where you want an email link to be inserted. One quick way is to put the link text in a <span> with its “id” attribute set, like this:

<p><span id="contactMe">email me<span> for more information.</p>

(Many WYSIWYG editors create id attributes for you automatically — there’s usually a “source code” or “detail” view that will let you check. I prefer human-readable id values like “contactMe,” but id=”span018″ or id=”g78956b” will work fine too. It doesn’t matter what the id is, as long as it’s unique within the page.)

Then call mwmw.guardMailto to make the link like this:

<script type="text/javascript">
new mwmw.guardMailto("contactMe","test","example");
</script>

This will link the text “email me” from the example above to the email address test@example.com.

Remember, this has to happen after the browser displays the original span. The quick and dirty way is to put the script in the page body after the original span. That’s how this site works — the email text in the footer of this page is immediately followed by JavaScript that makes it a link.

Want to See It in Action?

You can view source on this page (scroll all the way to the bottom; guardMailto is used in the footer). There’s also a basic sample page that shows the features, and a fancier sample page that demonstrates some of the cool things you can do if you throw prototype into the mix. The sample pages also demonstrate two different techniques for adding the links in an “onload” function, which is what I would recommend in most cases.

Options

If you want to set additional options, they should be passed as a JavaScript object literal, which looks like this:

{propertyName:propertyValue, AnotherPropertyName:anotherPropertyValue}

You can see all of these options in use on the basic sample page.

The options are (in alphabetical order):

  • domainSuffix: Set your top level domain if it isn’t “com” (e.g., “edu” or “org”). Don’t include the “.”

    new mwmw.guardMailto("contactMe", "test", "example", {domainSuffix:"org"});

    To make a link to test@example.org

  • linkAddress: Replace the original link text with the email address itself. To replace “test -at- example -dot- com” with “test@example.com”:

    new mwmw.guardMailto("contactMe", "test", "example", {linkAddress:true});

  • linkClass: Specify the HTML class attribute of the new link, so you can style it with CSS:

    new mwmw.guardMailto("contactMe", "test", "example", {linkClass:"emailLink"});

    If you want multiple styles, separate them with spaces:

    new mwmw.guardMailto("contactMe", "test", "example", {linkClass:"emailLink siteNavigation"});

  • linkId: Specify the HTML id attribute of the new link, so you can style it with CSS:

    new mwmw.guardMailto("contactMe", "test", "example", {linkId:"authorContact"});

  • linkHtml: Completely replace the original link. If the browser doesn’t support replacing the contents of an element, the original contents will be left unchanged:

    new mwmw.guardMailto("contactMe", "test", "example", {linkHtml:"<img class='icon' src='/emailicon' alt='click to email' / >"});

  • linkText: Replace the text of the original link. If the browser doesn’t support replacing the text of an element, the original text will be left unchanged:

    new mwmw.guardMailto("contactMe", "test", "example", {linkText:"email the author"});

    (If you want the link text to be the email address itself, use the linkAddress option instead.)

  • linkTitle: Specify the HTML title attribute of the new link. This is often displayed as a tooltip when the user hovers over the link:

    new mwmw.guardMailto("contactMe", "test", "example", {linkTitle:"Click to email the author"});

You can mix and match almost all of these:

new mwmw.guardMailto("contactMe", "test", "example", {linkClass:"deadAuthor european" linkText:"Franz Kafka" linkTitle:"Click to email the author"});

The options linkAddress, linkHtml, and linkText are exceptions to the mix and match rule. Since they all change the contents of the link that’s displayed, you should only use one of them at a time.

License

guardMailto is released under The MIT License.

Browsers:

guardMailto has been tested in recent versions of Firefox, Internet Explorer (5.5, 6, and 7 beta), Mozilla, Netscape, and Opera, on Windows 98SE, 2000, and XP.

Current Version

1.0.01, last updated 8.jul.2006.
View changelog.

Acknowledgments

Rich Thornett provided excellent suggestions on everything from nomenclature to tweaking the API. I’m grateful for his generosity with his time and expertise. Thanks are also due Kathy Cashel for suggestions on clarifying this documentation.

Feedback?

Find it useful? Find it useless? Bugs? Tested on a different browser/platform? Suggestions? I’d love to hear from you. Leave a comment, or email me using the link in the footer.

guardMailto update

Saturday, 8 July 2006

After implementing guardMailto on a few web sites, I realized I hadn’t done a good job of handling cases in which the link text should be the email address itself, e.g., test@example.com.

This:

new mwmw.guardMailto("contactMe", "test", "example", {linkText:"test@example.com"});

is not a good solution because it leaves a valid email address in the page body where spammers can find it. Oops.

If you’re comfortable writing JavaScript, you might realize that the value of linkText can be any expression that evaluates to a string. So you could hide the address by doing something like this:

new mwmw.guardMailto("contactMe", "test", "example", {linkText:("test"+String.fromCharCode(64)+"example."+"com")});

But that’s clunky, redundant, and less than user-friendly for web designers who don’t care to be JavaScript gurus. The obvious thing to do was to add an option to automatically replace the original link text with the address itself, so that’s why I did for version 1.0.01. Just set option linkAddress to true like this:

new mwmw.guardMailto("contactMe", "test", "example", {linkAddress:true});

On a related note, guardMailto is perhaps a little less secure than my original “munge” library in that the default implementation does include a user name and domain string in plain text in the page. The fancier sample page has been updated to demonstrate a technique that bypasses this limitation.

introducing guardMailto

Thursday, 29 June 2006

The Problem

If you put something like this in your website:

<a href="mailto:test@example.com">email me!</a>

spammers can identify that test@example.com is an email address with automated tools that review thousands of websites (analogous to the “spiders” used by search engines like Google and Yahoo). They can add your address to their databases. And eventually, they will surely do so. In fact, it turns out that spammers are pretty good at extracting anything that looks like an email address, whether it’s in a mailto: link or not.

First Generation Solutions

There are already several libraries (and some commercial products) that use JavaScript to dynamically create mailto: links. I even wrote one myself a couple of years ago when I was providing web hosting for a number of small businesses.

The underlying theory is that while spammers could easily get your email address by going to the site, loading the page, and looking at the results, very few spammers will invest the time necessary to do so. If the automated tool doesn’t return an email address, they won’t check each site by hand. The economics of spamming are contingent on the incremental cost of sending each email being very, very low — anything that requires the spammer to invest time eats into the profit margin.

Most of these products used the principal of graceful degradation: If JavaScript was enabled in your browser, you got a functional email link. If JavaScript wasn’t available, you got alternate content provided in a <noscript> tag, if the page author provided it — or maybe nothing at all. Code for this approach — including my “munge” library — generally followed the following format:

A JavaScript library would be included in the <head> section of the document:

<script type="text/javascript" src="emailLib.js></script>

(Don’t worry if you’re not familiar with reading and writing JavaScript code. You don’t need to be a JavaScript expert to use guardMailto, and you can safely skip these examples.)

Then, in the body of the page, there would be some inline JavaScript that used document.write() to insert the link into the page:

<script type="text/javascript">
document.write(makeAnEmailLink("stringEncryptingEmailAddress"));
</script>

And, if you were lucky, there’d be a <noscript> tag that would provide a fallback for users without JavaScript:

<noscript>
email: test (at) example (dot) com
</noscript>

Towards a Second Generation Solution

I observed several serious problems with my “munge” library:

  • It was too complicated and hard to use. Programmers seemed comfortable with it, but web designers often weren’t, and “ordinary” people struggled mightily with it.
  • It was inflexible. It worked ok for text links that were all by themselves, but it didn’t readily support linking an image, for example.
  • It didn’t play particularly well with many “what-you-see-is-what-you-get” (WYSIWIG) web page editors.
  • It put the burden of creating the fallback <noscript> support on the page author. Many page authors were confused about how to do this effectively, and many just didn’t bother.

In the intervening time, I’ve learned a lot about object-oriented JavaScript, and I’ve become an advocate of progressive enhancement as an alternative to graceful degradation. (unobtrusive JavaScript is a related buzzword; I prefer “progressive enhancement” because it’s a design philosophy that’s applicable to more than just JavaScript.)

Progressive enhancement reverses the paradigm of graceful degradation: start with a basic html page that works “as-is,” and then enhance the functionality of the basic page for browsers that support it. Progressive enhancement makes it impossible to strand users of older browsers by omitting a <noscript> tag. It also better supports users who have a modern browser but may have JavaScript disabled or restricted for reasons of security and/or corporate policy. Finally, it often better addresses the accessibility needs of users with visual or other impairments.

Conceptually, the progressive enhancement model looks like this.

We still start with a library included in the <head> section:

<script type="text/javascript" src="emailLib.js></script>

In the body of the page, we have the link information in a format that is easily human-readable, but less easily machine-readable:

email me at <span id="contactAddress">test (at) example (dot) com</span>

And then we have some JavaScript that turns the human-readable text into a clickable link:

<script type="text/javascript">
makeAnEmailLink("contactAddress","stringEncryptingEmailAddress")
</script>

That JavaScript code can be inline in the page body, but it can also be somewhere else, so we can separate the page content from the presentation logic.

There’s one significant catch: You can’t turn the text into a link until after the browser has displayed it in the page. That makes this code a good candidate for an “onload” event, which the browser will run after the page finishes loading.

Enough Talk, Where’s the Code?

You can download either the raw javascript guardMailto.js or a gzip archive guardMailto.js.gz.

guardMailto is released under The MIT License.

Instructions for adding guardMailto to your site are covered in using guardMailto.