Make Contact With hCards

You're probably well familiar with vCards, the common data containers for exchanging address information, business locations and contact info. They're most often seen attached to e-mails, and most mail clients let you double-click on them and automatically add a person's contact information to your computer's address book.

But on the web, vCards are invisible to search engines, and webmail apps often can't import vCard data properly -- not such great news for fans of web-based mail apps. Luckily, a solution has emerged: the hCard microformat.

Designed to be a simple, open and distributed format, hCards are an extension of XHTML that makes it easy to represent people, companies, organizations, and places. All the data encapsulated in an hCard maps directly to the vCard specification, so programs that can handle vCards can easily add hCard support as well (whether or not they do is up the creators).

This article is a wiki. You can expand or enhance it by logging in and clicking on the Edit tab at the top of the page.

hCard Overview

As with other microformats, the hCard uses semantic HTML or XHTML to add more meaning to your address data. Using a series of pre-defined class definitions, hCard creates a consistent format that can be easily recognized by search engine spiders and humans alike.

The root class name for hCard is "vcard," so the standard definition starts like this:

<div class="vcard">
 <a class="url fn" href="http://yoursite.com/">Your Name</a>
</div>

As you can see, the definition is wrapped in a <div> tag with the root class of vcard. The next line is an ordinary link to your website with your name as the link text. Note however the class definitions, url and fn. Obviously, url denotes the fact that this chunk of data is a URL. But what about that fn class?

It gets a little bit complicated due to some contradictions in the vCard spec, but generally you can think of "fn" as short for "formal name". There is also an n property that can be used, though n can be assumed to be the same as fn in most cases.

Full Example

So far, all we have is a name leading to a website. For many, that's all the contact info they're willing to give. But for the sake of example, let's consider Joe Monkey, an employee of ACME Banana company. Joe wants to offer up all of his contact information, so we would create an hCard that looks like this:

<div id="hcard-Joe-Monkey" class="vcard">
 <span class="fn">Joe Monkey</span>
 <div class="org">ACME Banana</div>
 <div class="adr">
 <span class="type">Work</span>:
 <div class="street-address">314 Monkey Avenue</div>
 <span class="locality">Monkey Island</span>,
 <abbr class="region" title="California">CA</abbr>
 <span class="postal-code">94301</span>
 <div class="country-name">USA</div>
</div>
<div class="tel">
 <span class="type">Work</span> +1-555-555-5555
</div>
<div class="tel">
 <span class="type">Fax</span> +1-555-555-5555
</div>
<div>Email:
 <span class="email">joe@acmebanana.com</span>
</div>

<a class="url" href="aim:goim?screenname=monkeybites">AIM</a>

Most of the class names here should be self-evident, save perhaps "locality", which just means the city or municipal area.

Note that in this case we're making a card for an individual at a company, so we've used separate definitions for fn and org. However, when dealing with a company listing it would be perfectly acceptable to combine the two into one line, like so:

<span class="fn org">ACME Banana</span>

Class Properties

The various class properties are as follows:

Required:

• fn
• n (family-name, given-name, additional-name, honorific-prefix, honorific-suffix)

Optional:

• nickname, sort-string
• url, email (type, value), tel2 (type, value)
• adr (post-office-box, extended-address, street-address, locality, region, postal-code, country-name, type, value), label
• geo (latitude, longitude), tz
• photo, logo, sound, bday
• title, role, org (organization-name, organization-unit)
• category, note
• class, key, mailer, uid, rev

Making and Using hCards

Even though it's human-readable and easy to write, there's no need to type out all your hCard markup by hand. The very handy hCard creator can handle the grunt work for you, generating some nice cut and paste code.

If you're displaying hCards dynamically (say as part of your favorite social network's profile page), just whip up a skeleton like the one above and replace the fake data with the variables from your database.

It's also worth noting that contact or profile pages aren't the only place you can use hCard. HCard markup works well inside a <cite> block, for instance when you're citing another blog and want to provide some basic contact info for the author of the blog.

Further Reading

• The Microformats Wiki has a few lists of example sites where you can see embedded hCards in use. Add your site if you want.

• The hCard specification lists more information about all the gritty details that can be held within hCards.

• This page was last modified 03:11, 16 May 2008.