using guardMailto

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.

Leave a Reply