hCard authoring tips

(Difference between revisions)

Jump to: navigation, search
m (Reverted edits by 766nj57 (Talk) to last version by Tantek)
Line 1: Line 1:
-
HOW THING OUT
+
<entry-title>hCard authoring tips</entry-title>
-
HOW ANYTHING OUT
+
;short URL
-
HOW EVERYTHING OUT
+
:http://ufs.cc/w/hcarda
-
HOW UNIVERSE OUT
+
This page contains useful tips and guidelines for how to author [[hcard|hCards]], either from scratch, or by adding markup to existing content.
-
HOW MAKE THING OUT
+
 
-
HOW MAKE ANYTHING OUT
+
'''Goal:''' The goal of this document is to provide some good intuitive guidelines that should make it as easy and as quick as possible for any web author to create hCards or add hCard markup to existing content.
-
HOW MAKE EVERYTHING OUT
+
 
-
HOW MAKE UNIVERSE OUT
+
'''Audience:''' Web authors, designers, IA's.  This document is written for easy consumption and understanding by any web designer who knows at least enough (X)HTML and CSS to use semantic HTML class names on elements (i.e. [[POSH]]) and write CSS selectors that apply styles to those class names.  Please help with clarifying/simplifying this document accordingly.
-
HOW THING BE OUT
+
 
-
HOW ANYTHING BE OUT
+
'''Author(s):''' [[User:Tantek|Tantek Çelik]], [[User:MarkRickerby|Mark Rickerby]]
-
HOW EVERYTHING BE OUT
+
 
-
HOW UNIVERSE BE OUT
+
== A 5 minute primer to using hCard ==
-
HOW MAKE THING BE OUT
+
 
-
HOW MAKE ANYTHING BE OUT
+
Let's imagine a static page that contains some personal contact details, the main part of which looks something like:
-
HOW MAKE EVERYTHING BE OUT
+
 
-
HOW MAKE UNIVERSE BE OUT
+
<source lang=html4strict>
-
HOW THING OUT
+
<div id="contact">
-
HOW ANYTHING OUT
+
  <h2>Contact Me</h2>
-
HOW EVERYTHING OUT
+
  <p>You can contact me via email to
-
HOW UNIVERSE OUT
+
  <a href="mailto:jane@example.com">jane@example.com</a>,
-
HOW MAKE THING OUT
+
  or send stuff to me at the following address:</p>
-
HOW MAKE ANYTHING OUT
+
  <p>255 Some Street,<br />
-
HOW MAKE EVERYTHING OUT
+
    Some Place,<br />
-
HOW MAKE UNIVERSE OUT
+
    Some Town</p>
-
HOW THING BE OUT
+
</div>
-
HOW ANYTHING BE OUT
+
</source>
-
HOW EVERYTHING BE OUT
+
 
-
HOW UNIVERSE BE OUT
+
This snippet has all the human readable information needed to produce a valid [[hcard|hCard]] representation - all that is necessary is to add some additional structure that defines each particular detail. The first thing to do is to add the <code>vcard</code> wrapper class to the enclosing <code>div</code>, which identifies this particular block as an [[hcard|hCard]]:
-
HOW MAKE THING BE OUT
+
 
-
HOW MAKE ANYTHING BE OUT
+
<source lang=html4strict>
-
HOW MAKE EVERYTHING BE OUT
+
<div id="contact" class="vcard">
-
HOW MAKE UNIVERSE BE OUT
+
</source>
-
HOW THING OUT
+
 
-
HOW ANYTHING OUT
+
One thing that is noticeably missing from this snippet is the name of who these contact details apply to - this makes the information presented  more ambiguous and harder to understand. It's good to be explicit with such things, and it just so happens that the name property is a compulsory field within an [[hcard|hCard]] as well. So let's add it, using the <code>fn</code> class:
-
HOW EVERYTHING OUT
+
 
-
HOW UNIVERSE OUT
+
<source lang=html4strict>
-
HOW MAKE THING OUT
+
<div id="contact" class="vcard">
-
HOW MAKE ANYTHING OUT
+
  <h2>Contact Me</h2>
-
HOW MAKE EVERYTHING OUT
+
  <h3 class="fn">Jane Doe</h3>
-
HOW MAKE UNIVERSE OUT
+
  <p>You can contact me via email to
-
HOW THING BE OUT
+
    <a href="mailto:jane@example.com">jane@example.com</a>,
-
HOW ANYTHING BE OUT
+
    or reach me at the following address:</p>
-
HOW EVERYTHING BE OUT
+
  <p>255 Some Street,<br />
-
HOW UNIVERSE BE OUT
+
    Some Town,<br />
-
HOW MAKE THING BE OUT
+
    Some Place</p>
-
HOW MAKE ANYTHING BE OUT
+
</div>
-
HOW MAKE EVERYTHING BE OUT
+
</source>
-
HOW MAKE UNIVERSE BE OUT
+
 
-
HOW THING OUT
+
Another thing we can do to improve the semantics of the snippet is to mark up the address with "adr", and use <code>div</code> tags since its not really a paragraph. At the same time, we should also get rid of the [http://tantek.com/log/2002/10.html#L20021022t1432 bed & breakfast] markup in the second paragraph, replacing it with structured classnames for the components of a mailing address: <code>adr</code>, <code>street-address</code>, <code>locality</code>, and <code>region</code>. We can also add the <code>email</code> class to the mailto link, to complete the structure of the [[hcard|hCard]]:
-
HOW ANYTHING OUT
+
 
-
HOW EVERYTHING OUT
+
<source lang=html4strict>
-
HOW UNIVERSE OUT
+
<div id="contact" class="vcard">
-
HOW MAKE THING OUT
+
  <h2>Contact Me</h2>
-
HOW MAKE ANYTHING OUT
+
  <h3 class="fn">Jane Doe</h3>
-
HOW MAKE EVERYTHING OUT
+
  <p>You can contact me via email to
-
HOW MAKE UNIVERSE OUT
+
    <a class="email" href="mailto:jane@example.com">jane@example.com</a>,
-
HOW THING BE OUT
+
    or reach me at the following address:</p>
-
HOW ANYTHING BE OUT
+
  <div class="adr">
-
HOW EVERYTHING BE OUT
+
    <div class="street-address">255 Some Street</div>
-
HOW UNIVERSE BE OUT
+
    <div class="locality">Some Town</div>
-
HOW MAKE THING BE OUT
+
    <div class="region">Some Place</div>
-
HOW MAKE ANYTHING BE OUT
+
  </div>
-
HOW MAKE EVERYTHING BE OUT
+
</div>
-
HOW MAKE UNIVERSE BE OUT
+
</source>
-
HOW THING OUT
+
 
-
HOW ANYTHING OUT
+
And that's all it takes!
-
HOW EVERYTHING OUT
+
 
-
HOW UNIVERSE OUT
+
Aside from the advantages of having such structured visible data, providing these additional class names also increases the visual design possibilities.
-
HOW MAKE THING OUT
+
 
-
HOW MAKE ANYTHING OUT
+
== Add To Address Book Links ==
-
HOW MAKE EVERYTHING OUT
+
When you update your contact info to include hCard markup, you can also include an "Add to Address Book" link so your users can download your contact info to their address book with one click of a hyperlink!
-
HOW MAKE UNIVERSE OUT
+
 
-
HOW THING BE OUT
+
Here is an example of such a link:
-
HOW ANYTHING BE OUT
+
 
-
HOW EVERYTHING BE OUT
+
<source lang=html4strict>
-
HOW UNIVERSE BE OUT
+
<a href="http://h2vx.com/vcf/tantek.com">
-
HOW MAKE THING BE OUT
+
Add to Address Book
-
HOW MAKE ANYTHING BE OUT
+
</a>
-
HOW MAKE EVERYTHING BE OUT
+
</source>
-
HOW MAKE UNIVERSE BE OUT
+
 
-
HOW THING OUT
+
Simply substitute the link to your hCard for the <kbd>tantek.com</kbd> URL fragment above (note that <code>http://</code> is implied, you can add it explicitly if you want).
-
HOW ANYTHING OUT
+
 
-
HOW EVERYTHING OUT
+
If you have more than one hCard on that page, you should put a unique ID attribute on each, and then put <kbd>%23yourIDhere</kbd> at the end of your href code where <kbd>yourIDhere</kbd> is the ID attribute value that you put on the hCard you are creating the link for.
-
HOW UNIVERSE OUT
+
 
-
HOW MAKE THING OUT
+
You can also use Brian Suda's hosted [[X2V]] service, or download and install the open source X2V XSLT yourself and run it on your own server instead of using an online hCard to vCard converter service.
-
HOW MAKE ANYTHING OUT
+
 
-
HOW MAKE EVERYTHING OUT
+
== Creating new hCards ==
-
HOW MAKE UNIVERSE OUT
+
Start with the [http://microformats.org/code/hcard/creator hCard creator], and for additional fields and properties (e.g. telephone numbers, instant messaging contacts), see the [[hcard-examples|hCard examples]] page.
-
HOW THING BE OUT
+
 
-
HOW ANYTHING BE OUT
+
== Adding hCard markup to existing content ==
-
HOW EVERYTHING BE OUT
+
 
-
HOW UNIVERSE BE OUT
+
=== Natural language hCard ===
-
HOW MAKE THING BE OUT
+
 
-
HOW MAKE ANYTHING BE OUT
+
Perhaps you have a traditional prose description of yourself.  Start by reading Jeremy Keith's article  "[http://adactio.com/journal/1122/ Adactio: Journal - Natural language hCard]" which provides a nice succinct introduction in the art of adding hCard markup to an existing prose biography.
-
HOW MAKE EVERYTHING BE OUT
+
 
-
HOW MAKE UNIVERSE BE OUT
+
Jeremy's recent post [http://adactio.com/journal/1393/ Year zero] also contains an inline hCard citation reference to "Malarkey" (who was being quoted) that is quite illustrative of how to markup a simple hyperlinked reference to someone by obvious nickname:
-
HOW THING OUT
+
 
-
HOW ANYTHING OUT
+
<source lang=html4strict>
-
HOW EVERYTHING OUT
+
<cite class="vcard">
-
HOW UNIVERSE OUT
+
<abbr class="fn" title="Andy Clarke">
-
HOW MAKE THING OUT
+
  <a href="http://www.stuffandnonsense.co.uk/malarkey/">Malarkey</a>
-
HOW MAKE ANYTHING OUT
+
</abbr>
-
HOW MAKE EVERYTHING OUT
+
</cite>
-
HOW MAKE UNIVERSE OUT
+
</source>
-
HOW THING BE OUT
+
 
-
HOW ANYTHING BE OUT
+
He could actually make this just a bit more semantic by explicitly noting that "Malarkey" is a nickname for Andy Clarke:
-
HOW EVERYTHING BE OUT
+
 
-
HOW UNIVERSE BE OUT
+
<source lang=html4strict>
-
HOW MAKE THING BE OUT
+
<cite class="vcard">
-
HOW MAKE ANYTHING BE OUT
+
<abbr class="fn" title="Andy Clarke">
-
HOW MAKE EVERYTHING BE OUT
+
  <a class="nickname" href="http://www.stuffandnonsense.co.uk/malarkey">Malarkey</a>
-
HOW MAKE UNIVERSE BE OUT
+
</abbr>
-
HOW THING OUT
+
</cite>
-
HOW ANYTHING OUT
+
</source>
-
HOW EVERYTHING OUT
+
 
-
HOW UNIVERSE OUT
+
Similarly, a shortened given name only (e.g. Julie instead of Juliette) reference to someone can be marked up as such, here with XFN added to the hyperlink:
-
HOW MAKE THING OUT
+
 
-
HOW MAKE ANYTHING OUT
+
<source lang=html4strict>
-
HOW MAKE EVERYTHING OUT
+
<span class="vcard">
-
HOW MAKE UNIVERSE OUT
+
<abbr class="fn" title="Juliette Melton">
-
HOW THING BE OUT
+
  <a class="url nickname" rel="friend" href="http://juliettemelton.com/">Julie</a>
-
HOW ANYTHING BE OUT
+
</abbr>
-
HOW EVERYTHING BE OUT
+
</span>
-
HOW UNIVERSE BE OUT
+
</source>
-
HOW MAKE THING BE OUT
+
 
-
HOW MAKE ANYTHING BE OUT
+
 
-
HOW MAKE EVERYTHING BE OUT
+
=== Minimal Markup Changes ===
-
HOW MAKE UNIVERSE BE OUT
+
 
-
HOW THING OUT
+
When adding hCard to existing content, keep in mind that hCard was designed for semantically enhancing existing content without affecting its presentation (or minimally so).  Thus: change as little markup as possible.  If you want to fix various pages to be valid XHTML etc., that's fine.
-
HOW ANYTHING OUT
+
 
-
HOW EVERYTHING OUT
+
In all examples below where it says to add an element with class name of "<code>xyz</code>", first look for an existing element that precisely surrounds the necessary content. Re-use that element by simply adding the class name "<code>xyz</code>" (meaning, add " xyz" (without quotes) to the element's existing class attribute, or add a new class attribute <code>class="xyz"</code> to elements without a class attribute).
-
HOW UNIVERSE OUT
+
 
-
HOW MAKE THING OUT
+
e.g.
-
HOW MAKE ANYTHING OUT
+
<source lang=html4strict><span>...</span></source>
-
HOW MAKE EVERYTHING OUT
+
would become:
-
HOW MAKE UNIVERSE OUT
+
<source lang=html4strict><span class="xyz">...</span></source>
-
HOW THING BE OUT
+
 
-
HOW ANYTHING BE OUT
+
and
-
HOW EVERYTHING BE OUT
+
<source lang=html4strict><span class="foo">...</span></source>
-
HOW UNIVERSE BE OUT
+
would become:
-
HOW MAKE THING BE OUT
+
<source lang=html4strict><span class="foo xyz">...</span></source>
-
HOW MAKE ANYTHING BE OUT
+
 
-
HOW MAKE EVERYTHING BE OUT
+
=== Find People or Organizations ===
-
HOW MAKE UNIVERSE BE OUT
+
Start with looking for all mentions of people or organizations on a page.  All of those are potential hCards.  Even more so if they are linked to their respective URLs (e.g. home pages / blogs).
-
HOW THING OUT
+
 
-
HOW ANYTHING OUT
+
If a person (or organization, henceforth shortened to just "'''person/org'''") is mentioned several times on a page, consider marking up the mention which is the most detailed, definitive, or otherwise thorough as an hCard.  Ideally you might want to mark up ''all'' instances of a person/org as hCards, but for now, just keep it simple and markup the most representative instance. (Perhaps the most "definitive" instance, which could also then be marked up with a <code><nowiki><dfn></nowiki></code> element around the name of the person/org for additional semantic XHTML goodness.)
-
HOW EVERYTHING OUT
+
 
-
HOW UNIVERSE OUT
+
=== Determine The Surrounding Element for Each ===
-
HOW MAKE THING OUT
+
For each person/org that you want to turn into an hCard, find the smallest element that contains all the info about that person/org, and no info about any other person/org.
-
HOW MAKE ANYTHING OUT
+
 
-
HOW MAKE EVERYTHING OUT
+
Add the class name "<code>vcard</code>" to that element.
-
HOW MAKE UNIVERSE OUT
+
 
-
HOW THING BE OUT
+
If there is no such element (perhaps the nearest enclosing element contains more than one person/org), then add a <code><nowiki><span class="vcard">...</span></nowiki></code> or <code><nowiki><div class="vcard">...</div></nowiki></code> that wraps the info about that person/org and just that person/org.
-
HOW ANYTHING BE OUT
+
 
-
HOW EVERYTHING BE OUT
+
The rest of the markup for this hCard MUST go ''inside'' that element with the class name "vcard".
-
HOW UNIVERSE BE OUT
+
 
-
HOW MAKE THING BE OUT
+
=== The Importance of Names ===
-
HOW MAKE ANYTHING BE OUT
+
The name is the one required property of hCard.  Thus be sure to mark up the name of the person with the class name "fn".  For names of people which are two simple words (text separated by space) and where the first word is their given name and the second word is their family name, the class name "fn" is sufficient. E.g.
-
HOW MAKE EVERYTHING BE OUT
+
 
-
HOW MAKE UNIVERSE BE OUT
+
<source lang=html4strict><div class="vcard"><span class="fn">Rohit Khare</span></div></source>
-
HOW THING OUT
+
 
-
HOW ANYTHING OUT
+
For people with <span id="middle-name" class="hcard-faq-ref">middle names</span> or multi-word last names, you must mark them up with the "n" property and its sub-properties "given-name" and "family-name" (and "additional-name" when a middle name is included) e.g.:
-
HOW EVERYTHING OUT
+
<source lang=html4strict>
-
HOW UNIVERSE OUT
+
<!-- 1. middle name example -->
-
HOW MAKE THING OUT
+
 
-
HOW MAKE ANYTHING OUT
+
<div class="vcard"><span class="fn n">
-
HOW MAKE EVERYTHING OUT
+
<span class="given-name">Erin</span>
-
HOW MAKE UNIVERSE OUT
+
<span class="additional-name">Jo</abbr>
-
HOW THING BE OUT
+
<span class="family-name">Richey</span>
-
HOW ANYTHING BE OUT
+
</span></div>
-
HOW EVERYTHING BE OUT
+
 
-
HOW UNIVERSE BE OUT
+
<!-- 2. middle initial only -->
-
HOW MAKE THING BE OUT
+
 
-
HOW MAKE ANYTHING BE OUT
+
<div class="vcard"><span class="fn n">
-
HOW MAKE EVERYTHING BE OUT
+
<span class="given-name">Eric</span>
-
HOW MAKE UNIVERSE BE OUT
+
<abbr class="additional-name">A.</abbr>
-
HOW THING OUT
+
<span class="family-name">Meyer</span>
-
HOW ANYTHING OUT
+
</span></div>
-
HOW EVERYTHING OUT
+
 
-
HOW UNIVERSE OUT
+
<!-- 3. middle initial with expansion -->
-
HOW MAKE THING OUT
+
 
-
HOW MAKE ANYTHING OUT
+
<div class="vcard"><span class="fn n">
-
HOW MAKE EVERYTHING OUT
+
<span class="given-name">Emily</span>
-
HOW MAKE UNIVERSE OUT
+
<abbr class="additional-name" title="Paige">P.</abbr>
-
HOW THING BE OUT
+
<span class="family-name">Lewis</span>
-
HOW ANYTHING BE OUT
+
</span></div>
-
HOW EVERYTHING BE OUT
+
 
-
HOW UNIVERSE BE OUT
+
<!-- 4. Norwegian name indicated with lang attribute -->
-
HOW MAKE THING BE OUT
+
 
-
HOW MAKE ANYTHING BE OUT
+
<div class="vcard"><span class="fn n" lang="no">
-
HOW MAKE EVERYTHING BE OUT
+
<span class="given-name">Håkon</span>
-
HOW MAKE UNIVERSE BE OUT
+
<span class="additional-name">Wium</span>
-
HOW THING OUT
+
<span class="family-name">Lie</span>
-
HOW ANYTHING OUT
+
</span></div>
-
HOW EVERYTHING OUT
+
 
-
HOW UNIVERSE OUT
+
<!-- 5. multiword family name example -->
-
HOW MAKE THING OUT
+
 
-
HOW MAKE ANYTHING OUT
+
<div class="vcard"><span class="fn n">
-
HOW MAKE EVERYTHING OUT
+
<span class="given-name">Thomas</span>
-
HOW MAKE UNIVERSE OUT
+
<span class="family-name">Vander Wal</span>
-
HOW THING BE OUT
+
</span></div>
-
HOW ANYTHING BE OUT
+
</source>
-
HOW EVERYTHING BE OUT
+
 
-
HOW UNIVERSE BE OUT
+
 
-
HOW MAKE THING BE OUT
+
==== Organization hCards ====
-
HOW MAKE ANYTHING BE OUT
+
 
-
HOW MAKE EVERYTHING BE OUT
+
For hCards for organizations, be sure to put both the "fn" and "org" class names on the same element. Having those be the same is the hint to hCard consumers that the hCard represents an organization rather than a person. E.g.
-
HOW MAKE UNIVERSE BE OUT
+
<source lang=html4strict><div class="vcard"><span class="fn org">Technorati</span></div></source>
-
HOW THING OUT
+
 
-
HOW ANYTHING OUT
+
=== Link it up ===
-
HOW EVERYTHING OUT
+
<span id="Representative_URLs"> </span>
-
HOW UNIVERSE OUT
+
Add links to your website, your social network profiles and other sites that represent ''you'' specifically to your hCard with the class name <code>url</code>. Here is an example with a personal site, and Twitter and Flickr profile URLs:
-
HOW MAKE THING OUT
+
 
-
HOW MAKE ANYTHING OUT
+
<source lang=html4strict>
-
HOW MAKE EVERYTHING OUT
+
<span class="vcard">
-
HOW MAKE UNIVERSE OUT
+
<span class="fn">Tantek Çelik</span>,
-
HOW THING BE OUT
+
<a class="url" href="http://tantek.com/">my site</a>,
-
HOW ANYTHING BE OUT
+
<a class="url" href="http://twitter.com/t">twitter</a>, and
-
HOW EVERYTHING BE OUT
+
<a class="url" href="http://flickr.com/tantek">flickr</a>.
-
HOW UNIVERSE BE OUT
+
</span>
-
HOW MAKE THING BE OUT
+
</source>
-
HOW MAKE ANYTHING BE OUT
+
 
-
HOW MAKE EVERYTHING BE OUT
+
==== connect with yourself ====
-
HOW MAKE UNIVERSE BE OUT
+
If you are marking up an hCard on your own site, be sure to also add the [[xfn|XFN]] <code>rel="me"</code> attribute to indicate that those profile pages are additional facets of your online identity.  See <cite>[http://gmpg.org/xfn/and/#idconsolidation Identity consolidation with XFN]</cite> for more details.
-
HOW THING OUT
+
 
-
HOW ANYTHING OUT
+
<source lang=html4strict>
-
HOW EVERYTHING OUT
+
<span class="vcard">
-
HOW UNIVERSE OUT
+
<span class="fn">Tantek Çelik</span>,
-
HOW MAKE THING OUT
+
<a rel="me" class="url" href="http://tantek.com/">my site</a>,
-
HOW MAKE ANYTHING OUT
+
<a rel="me" class="url" href="http://twitter.com/t">twitter</a>, and
-
HOW MAKE EVERYTHING OUT
+
<a rel="me" class="url" href="http://flickr.com/tantek">flickr</a>.
-
HOW MAKE UNIVERSE OUT
+
</span>
-
HOW THING BE OUT
+
</source>
-
HOW ANYTHING BE OUT
+
 
-
HOW EVERYTHING BE OUT
+
Edit your profiles on those other sites and set the "home page", "URL", or "blog" fields to link back to your own site to connect your social network profiles together.
-
HOW UNIVERSE BE OUT
+
 
-
HOW MAKE THING BE OUT
+
Sites like http://huffduffer.com and [[Firefox]] plugins like [[Identify]] use APIs like the Google Social Graph API (which indexes rel-me links) to automatically connect your profiles for you in their user interfaces.
-
HOW MAKE ANYTHING BE OUT
+
 
-
HOW MAKE EVERYTHING BE OUT
+
See [http://klinger.io/ Andreas Klinger's home page] for a nice, simple, real world example of a personal site with hCard that links to other profiles.
-
HOW MAKE UNIVERSE BE OUT
+
 
-
HOW THING OUT
+
==== name and URL only ====
-
HOW ANYTHING OUT
+
One of the most common patterns for person/orgs in web content is the name of the person/org, hyperlinked to their definitive/preferred web site.
-
HOW EVERYTHING OUT
+
 
-
HOW UNIVERSE OUT
+
When you simply reference a person by name with URL, you can simplify the markup.
-
HOW MAKE THING OUT
+
 
-
HOW MAKE ANYTHING OUT
+
<source lang=html4strict>
-
HOW MAKE EVERYTHING OUT
+
<span class="vcard">
-
HOW MAKE UNIVERSE OUT
+
<a href="http://theryanking.com" class="fn url">Ryan King</a>
-
HOW THING BE OUT
+
</span>
-
HOW ANYTHING BE OUT
+
</source>
-
HOW EVERYTHING BE OUT
+
 
-
HOW UNIVERSE BE OUT
+
This works because the HTML class attribute takes a space separated set of class names.
-
HOW MAKE THING BE OUT
+
 
-
HOW MAKE ANYTHING BE OUT
+
Blogrolls are a good example of lists of people with name and URL (see also [[xoxo|XOXO]]).
-
HOW MAKE EVERYTHING BE OUT
+
 
-
HOW MAKE UNIVERSE BE OUT
+
=== Titles ===
-
HOW THING OUT
+
If the person's job title is mentioned, mark it up with <code><nowiki><span class="title">...</span></nowiki></code>.
-
HOW ANYTHING OUT
+
 
-
HOW EVERYTHING OUT
+
Though typical vCards/hCards have only a single job title, if someone has several job titles listed say in a comma delimited list, just markup the whole lot of them with one big <code><nowiki><span class="title">...</span></nowiki></code>.
-
HOW UNIVERSE OUT
+
 
-
HOW MAKE THING OUT
+
View source on the [http://tantek.com/microformats/2006/03-01-TechPlenAgenda.html W3C Technical Plenary Agenda] for examples of people with multiple titles.
-
HOW MAKE ANYTHING OUT
+
 
-
HOW MAKE EVERYTHING OUT
+
=== Other affiliations ===
-
HOW MAKE UNIVERSE OUT
+
As vCard seems to imply a model of a person only being associated with one organization (at least certainly that's how most [[vcard-implementations]] appear to be written), consider placing other affiliations and info about the person into <code><nowiki><span class="note">...</span></nowiki></code> elements.  You can have more than one; converters will simply append them all in source order.
-
HOW THING BE OUT
+
 
-
HOW ANYTHING BE OUT
+
View source on the [http://tantek.com/microformats/2006/03-01-TechPlenAgenda.html W3C Technical Plenary Agenda] for examples of people with additional affiliations (such as W3C Working Groups) marked up inside "note" elements.
-
HOW EVERYTHING BE OUT
+
 
-
HOW UNIVERSE BE OUT
+
Sometimes text in a document near a person/contact will explain *why* that person should be contacted.  Such information is also useful to have in a "note" element.
-
HOW MAKE THING BE OUT
+
 
-
HOW MAKE ANYTHING BE OUT
+
View source on the [http://rbach.priv.at/repos/misc/microformatting/ETech2006/invite.html O'Reilly ETech 2006 invite] for examples of people with additional "For ... " reasons marked up as "note" elements.
-
HOW MAKE EVERYTHING BE OUT
+
 
-
HOW MAKE UNIVERSE BE OUT
+
=== Set the lang when different ===
-
HOW THING OUT
+
In an English language document (<code>lang="en"</code>), be sure to markup the element surrounding any non-English names of people, companies, titles, notes etc. with a lang attribute with the appropriate value.
-
HOW ANYTHING OUT
+
 
-
HOW EVERYTHING OUT
+
E.g. Spanish names in an english document should be marked up with (<code>lang="es"</code>) on their elements.
-
HOW UNIVERSE OUT
+
 
-
HOW MAKE THING OUT
+
View source on the [http://tantek.com/microformats/2006/03-01-TechPlenAgenda.html W3C Technical Plenary Agenda], specifically Ignacio Marín, for an example of a person and org marked up with a <code>lang</code> attribute.
-
HOW MAKE ANYTHING OUT
+
 
-
HOW MAKE EVERYTHING OUT
+
=== Phone Numbers ===
-
HOW MAKE UNIVERSE OUT
+
Add a few phone numbers like this:
-
HOW THING BE OUT
+
<source lang=html4strict>
-
HOW ANYTHING BE OUT
+
<div class="tel">
-
HOW EVERYTHING BE OUT
+
  <span class="type">work</span>:
-
HOW UNIVERSE BE OUT
+
  <span class="value">+1-250-555-2142</span>
-
HOW MAKE THING BE OUT
+
</div>
-
HOW MAKE ANYTHING BE OUT
+
<div class="tel">
-
HOW MAKE EVERYTHING BE OUT
+
  <span class="type">work</span> toll free:
-
HOW MAKE UNIVERSE BE OUT
+
  <span class="value">+1-800-555-1855</span>
-
HOW THING OUT
+
</div>
-
HOW ANYTHING OUT
+
<div class="tel">
-
HOW EVERYTHING OUT
+
  <span class="type">work</span>
-
HOW UNIVERSE OUT
+
  <span class="type">fax</span>:
-
HOW MAKE THING OUT
+
  <span class="value">+1-250-555-2135</span>
-
HOW MAKE ANYTHING OUT
+
</div>
-
HOW MAKE EVERYTHING OUT
+
</source>
-
HOW MAKE UNIVERSE OUT
+
 
-
HOW THING BE OUT
+
This will display something like:
-
HOW ANYTHING BE OUT
+
 
-
HOW EVERYTHING BE OUT
+
work: +1-250-555-2142
-
HOW UNIVERSE BE OUT
+
work toll free: +1-800-555-1855
-
HOW MAKE THING BE OUT
+
work fax: +1-250-555-2135
-
HOW MAKE ANYTHING BE OUT
+
 
-
HOW MAKE EVERYTHING BE OUT
+
The list of tel types are: <code>voice</code> [which is the default if "type" is unspecified], <code>home</code>, <code>msg</code>, <code>work</code>, <code>pref</code>, <code>fax</code>, <code>cell</code>, <code>video</code>, <code>pager</code>, <code>bbs</code>, <code>modem</code>, <code>car</code>, <code>isdn</code>, <code>pcs</code>.  As shown in the last example above, a tel may have multiple types.  See [[hcard#type_subproperty_values|hCard: Type Subproperty Values]] for the official list.
-
HOW MAKE UNIVERSE BE OUT
+
 
-
HOW THING OUT
+
=== Photographs ===
-
HOW ANYTHING OUT
+
Mark up representative image(s) of the person/org with the class name "<code>photo</code>", e.g.:
-
HOW EVERYTHING OUT
+
 
-
HOW UNIVERSE OUT
+
<source lang=html4strict><img class="photo" src="http://www.factorycity.net/images/avatar.jpg" alt="" /></source>
-
HOW MAKE THING OUT
+
 
-
HOW MAKE ANYTHING OUT
+
If your name is not already marked up (see the Names section above), and your first and last name consist of only two words, you can set the alt attribute for the image as your name. In this case, include the "fn" class name along with the "photo" class name in the class attribute:
-
HOW MAKE EVERYTHING OUT
+
 
-
HOW MAKE UNIVERSE OUT
+
<source lang=html4strict><img class="photo fn" src="http://www.factorycity.net/images/avatar.jpg" alt="Chris Messina" /></source>
-
HOW THING BE OUT
+
 
-
HOW ANYTHING BE OUT
+
To ensure that the picture is not left out whenever a hcard is converted into a vcard, the external URI should be replaced with the actual encoded picture data as follows:
-
HOW EVERYTHING BE OUT
+
 
-
HOW UNIVERSE BE OUT
+
<source lang=html4strict><img alt="photo" class="photo" src="data:image/jpeg;base64,/9j/4AAQSkZJRgAB[...]RRxTwKpCP//Z" /></source>
-
HOW MAKE THING BE OUT
+
 
-
HOW MAKE ANYTHING BE OUT
+
An easy way to encode a contact picture is to use some application which can export vcard files including contact picture, as the freeware [http://www.palm.com/us/software/desktop/ Palm Desktop] does.
-
HOW MAKE EVERYTHING BE OUT
+
 
-
HOW MAKE UNIVERSE BE OUT
+
=== Geographic Coordinates ===
-
HOW THING OUT
+
Add your geographic coordinates:
-
HOW ANYTHING OUT
+
<source lang=html4strict>
-
HOW EVERYTHING OUT
+
<span class="geo">
-
HOW UNIVERSE OUT
+
  <span class="latitude">48.430092246</span>
-
HOW MAKE THING OUT
+
  <span class="longitude">-123.364348450</span>
-
HOW MAKE ANYTHING OUT
+
</span>
-
HOW MAKE EVERYTHING OUT
+
</source>
-
HOW MAKE UNIVERSE OUT
+
 
-
HOW THING BE OUT
+
A more human friendly version would be implemented as follows:
-
HOW ANYTHING BE OUT
+
 
-
HOW EVERYTHING BE OUT
+
<source lang=html4strict>
-
HOW UNIVERSE BE OUT
+
<div class="geo">
-
HOW MAKE THING BE OUT
+
<abbr class="latitude" title="-31.388333">31&deg;23&#39;18&quot;S</abbr>,
-
HOW MAKE ANYTHING BE OUT
+
<abbr class="longitude" title="-57.960556">57&deg;57&#39;38&quot;O</abbr>
-
HOW MAKE EVERYTHING BE OUT
+
</div>
-
HOW MAKE UNIVERSE BE OUT
+
</source>
-
HOW THING OUT
+
 
-
HOW ANYTHING OUT
+
That will look like this:  31°23'18"S, 57°57'38"O.
-
HOW EVERYTHING OUT
+
 
-
HOW UNIVERSE OUT
+
Note that the degree, minute and seconds characters should go encoded as in the source code example above to prevent that the browser to confuses the character encoding used by the page and shows wrong characters, like chinese characters where accents should be displayed.
-
HOW MAKE THING OUT
+
 
-
HOW MAKE ANYTHING OUT
+
A good place to get your coordinate values in both formats is Wikipedia. Look for the article on your city and click the human friendly coordinates to load a page with the decimal values.
-
HOW MAKE EVERYTHING OUT
+
 
-
HOW MAKE UNIVERSE OUT
+
=== Fragments and linking ===
-
HOW THING BE OUT
+
 
-
HOW ANYTHING BE OUT
+
An hCard is a logical piece of content that people might like to link to. If it's on a page with other content, it can be hard to link to just the one hCard, unless you have a fragment identifier to use. In HTML, you can create fragment identifiers by adding an 'id' attribute to any element. It is good practice to add an 'id' attribute to an hCard, e.g.
-
HOW EVERYTHING BE OUT
+
 
-
HOW UNIVERSE BE OUT
+
<source lang=html4strict>
-
HOW MAKE THING BE OUT
+
<span id="my-hCard" class="vcard">
-
HOW MAKE ANYTHING BE OUT
+
<a class="url fn" href="http://suda.co.uk">
-
HOW MAKE EVERYTHING BE OUT
+
  Brian Suda
-
HOW MAKE UNIVERSE BE OUT
+
</a>
 +
</span>
 +
</source>
 +
 
 +
 
 +
=== Canonical hCard within a site ===
 +
 
 +
Nearly every social website has profile URLs for its members, typically [[hcard-supporting-user-profiles|with hCard]].
 +
 
 +
Most of the pages on such websites link those canonical user profile URLs on the site itself with the icon and/or name the user.  It makes sense to explicitly markup those links with both class names "url" and "uid", e.g. on a list of Twitter friends (note the additional use of the [[XOXO]] microformat) that might be hosted on Twitter itself:
 +
 
 +
<source lang=html4strict>
 +
<ul class="xoxo">
 +
<li class="vcard">
 +
  <a class="url uid" href="http://twitter.com/briansuda">
 +
  <img class="fn logo" src="b-icon.jpg" alt="Brian Suda" />
 +
  </a>
 +
</li>
 +
<li class="vcard">
 +
  <a class="url uid" href="http://twitter.com/pspmikek">
 +
  <img class="fn logo" src="m-icon.jpg" alt="Michael Kaply" />
 +
  </a>
 +
</li>
 +
<li>
 +
  <a class="url uid" href="http://twitter.com/t">
 +
  <img class="fn logo" src="t-icon.jpg" alt="Tantek Çelik" />
 +
  </a>
 +
</li>
 +
</ul>
 +
</source>
 +
 
 +
Another example: event sites that list and link to user profiles of the people attending an event (e.g. Upcoming.org).
 +
 
 +
=== URL of an hCard being the page itself ===
 +
The canonical hCard within a site (as noted above) often has hCard markup itself, and it's useful to markup the page itself as the URL for that hCard.
 +
 
 +
So how do you markup the URL of an hCard where the URL is the page itself?
 +
 
 +
A few variants have been observed in real-world publishing, each of which implies a solution:
 +
 
 +
# '''Profile self-hyperlinking with name/photo.''' Many (most?) [[hcard-supporting-user-profiles]] sites hyperlink the person's name (e.g. [http://www.myspace.com/irhetoric Myspace irhetoric]) and/or image (e.g. [http://upcoming.yahoo.com/user/6623 Upcoming tantek]) on their profile to the profile itself.  This is a common design pattern. In this case the answer is obvious: simply add <code>class="url uid"</code> to the existing self-hyperlink.
 +
# '''Profiles with a "profile" link and/or dynamic content.''' Some sites have a "Profile" navigation link which is clickable even on the profile itself (e.g. on [http://twitter.com/ Twitter] login and go to your profile). In some cases the "Profile" link is highlighted among other navigation links to indicate that it's what is currently visible among the nav options (e.g. [http://www.last.fm/ last.fm] - login and go to your profile).  Both of these sites have dynamic content on profile pages, and thus could also label such self-hyperlinks with text like "Reload" or "Refresh" - accurately indicating to the user that when they clicked the link, it wouldn't change the URL in their browser address bar, but would reload the page, likely visibly updating the page.  In both these cases, the answer is the same as the first case above: simply add <code>class="url uid"</code> to the existing self-hyperlink.
 +
# '''Profiles without apparent self-hyperlinks.''' Some sites' profile pages (e.g. [http://flickr.com/people/tantek/ Flickr tantek]) have no self-hyperlink, possibly because their content is more static, and a visible self-hyperlink would appear to "do nothing" when clicked, either frustrating the user, or making them think the site was broken.  For these sites, the author can include an empty hyperlink with an empty href attribute (which is resolved as a relative URL to the page itself) to provide an invisible hyperlink to the page itself which is thus both not typically clickable (since it takes up no space), nor has any content which could be erroneously read by a screen reader. E.g. <code>&lt;a class="url" href=""&gt;&lt;/a&gt;</code>. This authoring suggestion is probably good enough to handle this third, perhaps rarest case, though it would be useful to to have some test cases that can be run in various browsers / assistive technologies to see what they do. Another (lengthier) suggestion would be to use [[value-class-pattern]] value-title technique, e.g.: <code><nowiki>&lt;span class="url uid"&gt;&lt;span class="value-title" title="http://example.com/user/john"&gt; &lt;/span&gt;&lt;/span&gt;</nowiki></code>.
 +
 
 +
=== More tips and guidelines ===
 +
Feel free to add more tips that experience has taught you while marking up hCards, even if all you add is a brief catch phrase that reminds you.
 +
 
 +
* How to note some text, so you can make a comment like who your admin assistant is.
 +
* More inline code examples, perhaps one for each section (suggestion from Cdevroe)
 +
* (suggestion from brian) you mention blogroll, this might be out of scope, but you could mention that XFN and hCard can be interweaved - it is not one or the other
 +
* ...
 +
 
 +
== Related Pages ==
 +
{{hcard-related-pages}}

Revision as of 06:48, 20 August 2013

short URL
http://ufs.cc/w/hcarda

This page contains useful tips and guidelines for how to author hCards, either from scratch, or by adding markup to existing content.

Goal: The goal of this document is to provide some good intuitive guidelines that should make it as easy and as quick as possible for any web author to create hCards or add hCard markup to existing content.

Audience: Web authors, designers, IA's. This document is written for easy consumption and understanding by any web designer who knows at least enough (X)HTML and CSS to use semantic HTML class names on elements (i.e. POSH) and write CSS selectors that apply styles to those class names. Please help with clarifying/simplifying this document accordingly.

Author(s): Tantek Çelik, Mark Rickerby

Contents

A 5 minute primer to using hCard

Let's imagine a static page that contains some personal contact details, the main part of which looks something like:

<div id="contact">
  <h2>Contact Me</h2>
  <p>You can contact me via email to 
   <a href="mailto:jane@example.com">jane@example.com</a>, 
   or send stuff to me at the following address:</p>
  <p>255 Some Street,<br />
     Some Place,<br />
     Some Town</p>
</div>

This snippet has all the human readable information needed to produce a valid hCard representation - all that is necessary is to add some additional structure that defines each particular detail. The first thing to do is to add the vcard wrapper class to the enclosing div, which identifies this particular block as an hCard:

<div id="contact" class="vcard">

One thing that is noticeably missing from this snippet is the name of who these contact details apply to - this makes the information presented more ambiguous and harder to understand. It's good to be explicit with such things, and it just so happens that the name property is a compulsory field within an hCard as well. So let's add it, using the fn class:

<div id="contact" class="vcard">
   <h2>Contact Me</h2>
   <h3 class="fn">Jane Doe</h3>
   <p>You can contact me via email to 
    <a href="mailto:jane@example.com">jane@example.com</a>, 
    or reach me at the following address:</p>
   <p>255 Some Street,<br />
     Some Town,<br />
     Some Place</p>
</div>

Another thing we can do to improve the semantics of the snippet is to mark up the address with "adr", and use div tags since its not really a paragraph. At the same time, we should also get rid of the bed & breakfast markup in the second paragraph, replacing it with structured classnames for the components of a mailing address: adr, street-address, locality, and region. We can also add the email class to the mailto link, to complete the structure of the hCard:

<div id="contact" class="vcard">
   <h2>Contact Me</h2>
   <h3 class="fn">Jane Doe</h3>
   <p>You can contact me via email to 
    <a class="email" href="mailto:jane@example.com">jane@example.com</a>, 
    or reach me at the following address:</p>
   <div class="adr">
     <div class="street-address">255 Some Street</div>
     <div class="locality">Some Town</div>
     <div class="region">Some Place</div>
   </div>
</div>

And that's all it takes!

Aside from the advantages of having such structured visible data, providing these additional class names also increases the visual design possibilities.

Add To Address Book Links

When you update your contact info to include hCard markup, you can also include an "Add to Address Book" link so your users can download your contact info to their address book with one click of a hyperlink!

Here is an example of such a link:

<a href="http://h2vx.com/vcf/tantek.com">
Add to Address Book
</a>

Simply substitute the link to your hCard for the tantek.com URL fragment above (note that http:// is implied, you can add it explicitly if you want).

If you have more than one hCard on that page, you should put a unique ID attribute on each, and then put %23yourIDhere at the end of your href code where yourIDhere is the ID attribute value that you put on the hCard you are creating the link for.

You can also use Brian Suda's hosted X2V service, or download and install the open source X2V XSLT yourself and run it on your own server instead of using an online hCard to vCard converter service.

Creating new hCards

Start with the hCard creator, and for additional fields and properties (e.g. telephone numbers, instant messaging contacts), see the hCard examples page.

Adding hCard markup to existing content

Natural language hCard

Perhaps you have a traditional prose description of yourself. Start by reading Jeremy Keith's article "Adactio: Journal - Natural language hCard" which provides a nice succinct introduction in the art of adding hCard markup to an existing prose biography.

Jeremy's recent post Year zero also contains an inline hCard citation reference to "Malarkey" (who was being quoted) that is quite illustrative of how to markup a simple hyperlinked reference to someone by obvious nickname:

<cite class="vcard">
 <abbr class="fn" title="Andy Clarke">
  <a href="http://www.stuffandnonsense.co.uk/malarkey/">Malarkey</a>
 </abbr>
</cite>

He could actually make this just a bit more semantic by explicitly noting that "Malarkey" is a nickname for Andy Clarke:

<cite class="vcard">
 <abbr class="fn" title="Andy Clarke">
  <a class="nickname" href="http://www.stuffandnonsense.co.uk/malarkey">Malarkey</a>
 </abbr>
</cite>

Similarly, a shortened given name only (e.g. Julie instead of Juliette) reference to someone can be marked up as such, here with XFN added to the hyperlink:

<span class="vcard">
 <abbr class="fn" title="Juliette Melton">
  <a class="url nickname" rel="friend" href="http://juliettemelton.com/">Julie</a>
 </abbr>
</span>


Minimal Markup Changes

When adding hCard to existing content, keep in mind that hCard was designed for semantically enhancing existing content without affecting its presentation (or minimally so). Thus: change as little markup as possible. If you want to fix various pages to be valid XHTML etc., that's fine.

In all examples below where it says to add an element with class name of "xyz", first look for an existing element that precisely surrounds the necessary content. Re-use that element by simply adding the class name "xyz" (meaning, add " xyz" (without quotes) to the element's existing class attribute, or add a new class attribute class="xyz" to elements without a class attribute).

e.g.

<span>...</span>

would become:

<span class="xyz">...</span>

and

<span class="foo">...</span>

would become:

<span class="foo xyz">...</span>

Find People or Organizations

Start with looking for all mentions of people or organizations on a page. All of those are potential hCards. Even more so if they are linked to their respective URLs (e.g. home pages / blogs).

If a person (or organization, henceforth shortened to just "person/org") is mentioned several times on a page, consider marking up the mention which is the most detailed, definitive, or otherwise thorough as an hCard. Ideally you might want to mark up all instances of a person/org as hCards, but for now, just keep it simple and markup the most representative instance. (Perhaps the most "definitive" instance, which could also then be marked up with a <dfn> element around the name of the person/org for additional semantic XHTML goodness.)

Determine The Surrounding Element for Each

For each person/org that you want to turn into an hCard, find the smallest element that contains all the info about that person/org, and no info about any other person/org.

Add the class name "vcard" to that element.

If there is no such element (perhaps the nearest enclosing element contains more than one person/org), then add a <span class="vcard">...</span> or <div class="vcard">...</div> that wraps the info about that person/org and just that person/org.

The rest of the markup for this hCard MUST go inside that element with the class name "vcard".

The Importance of Names

The name is the one required property of hCard. Thus be sure to mark up the name of the person with the class name "fn". For names of people which are two simple words (text separated by space) and where the first word is their given name and the second word is their family name, the class name "fn" is sufficient. E.g.

<div class="vcard"><span class="fn">Rohit Khare</span></div>

For people with middle names or multi-word last names, you must mark them up with the "n" property and its sub-properties "given-name" and "family-name" (and "additional-name" when a middle name is included) e.g.:

<!-- 1. middle name example -->
 
<div class="vcard"><span class="fn n">
 <span class="given-name">Erin</span> 
 <span class="additional-name">Jo</abbr>
 <span class="family-name">Richey</span>
</span></div>
 
<!-- 2. middle initial only -->
 
<div class="vcard"><span class="fn n">
 <span class="given-name">Eric</span> 
 <abbr class="additional-name">A.</abbr>
 <span class="family-name">Meyer</span>
</span></div>
 
<!-- 3. middle initial with expansion -->
 
<div class="vcard"><span class="fn n">
 <span class="given-name">Emily</span> 
 <abbr class="additional-name" title="Paige">P.</abbr>
 <span class="family-name">Lewis</span>
</span></div>
 
<!-- 4. Norwegian name indicated with lang attribute -->
 
<div class="vcard"><span class="fn n" lang="no">
 <span class="given-name">Håkon</span> 
 <span class="additional-name">Wium</span>
 <span class="family-name">Lie</span>
</span></div>
 
<!-- 5. multiword family name example -->
 
<div class="vcard"><span class="fn n">
 <span class="given-name">Thomas</span> 
 <span class="family-name">Vander Wal</span>
</span></div>


Organization hCards

For hCards for organizations, be sure to put both the "fn" and "org" class names on the same element. Having those be the same is the hint to hCard consumers that the hCard represents an organization rather than a person. E.g.

<div class="vcard"><span class="fn org">Technorati</span></div>

Link it up

Add links to your website, your social network profiles and other sites that represent you specifically to your hCard with the class name url. Here is an example with a personal site, and Twitter and Flickr profile URLs:

<span class="vcard">
 <span class="fn">Tantek Çelik</span>, 
 <a class="url" href="http://tantek.com/">my site</a>, 
 <a class="url" href="http://twitter.com/t">twitter</a>, and
 <a class="url" href="http://flickr.com/tantek">flickr</a>.
</span>

connect with yourself

If you are marking up an hCard on your own site, be sure to also add the XFN rel="me" attribute to indicate that those profile pages are additional facets of your online identity. See Identity consolidation with XFN for more details.

<span class="vcard">
 <span class="fn">Tantek Çelik</span>, 
 <a rel="me" class="url" href="http://tantek.com/">my site</a>, 
 <a rel="me" class="url" href="http://twitter.com/t">twitter</a>, and
 <a rel="me" class="url" href="http://flickr.com/tantek">flickr</a>.
</span>

Edit your profiles on those other sites and set the "home page", "URL", or "blog" fields to link back to your own site to connect your social network profiles together.

Sites like http://huffduffer.com and Firefox plugins like Identify use APIs like the Google Social Graph API (which indexes rel-me links) to automatically connect your profiles for you in their user interfaces.

See Andreas Klinger's home page for a nice, simple, real world example of a personal site with hCard that links to other profiles.

name and URL only

One of the most common patterns for person/orgs in web content is the name of the person/org, hyperlinked to their definitive/preferred web site.

When you simply reference a person by name with URL, you can simplify the markup.

<span class="vcard">
 <a href="http://theryanking.com" class="fn url">Ryan King</a>
</span>

This works because the HTML class attribute takes a space separated set of class names.

Blogrolls are a good example of lists of people with name and URL (see also XOXO).

Titles

If the person's job title is mentioned, mark it up with <span class="title">...</span>.

Though typical vCards/hCards have only a single job title, if someone has several job titles listed say in a comma delimited list, just markup the whole lot of them with one big <span class="title">...</span>.

View source on the W3C Technical Plenary Agenda for examples of people with multiple titles.

Other affiliations

As vCard seems to imply a model of a person only being associated with one organization (at least certainly that's how most vcard-implementations appear to be written), consider placing other affiliations and info about the person into <span class="note">...</span> elements. You can have more than one; converters will simply append them all in source order.

View source on the W3C Technical Plenary Agenda for examples of people with additional affiliations (such as W3C Working Groups) marked up inside "note" elements.

Sometimes text in a document near a person/contact will explain *why* that person should be contacted. Such information is also useful to have in a "note" element.

View source on the O'Reilly ETech 2006 invite for examples of people with additional "For ... " reasons marked up as "note" elements.

Set the lang when different

In an English language document (lang="en"), be sure to markup the element surrounding any non-English names of people, companies, titles, notes etc. with a lang attribute with the appropriate value.

E.g. Spanish names in an english document should be marked up with (lang="es") on their elements.

View source on the W3C Technical Plenary Agenda, specifically Ignacio Marín, for an example of a person and org marked up with a lang attribute.

Phone Numbers

Add a few phone numbers like this:

<div class="tel">
  <span class="type">work</span>:
  <span class="value">+1-250-555-2142</span>
</div>
<div class="tel">
  <span class="type">work</span> toll free: 
  <span class="value">+1-800-555-1855</span>
</div>
<div class="tel">
  <span class="type">work</span>
  <span class="type">fax</span>:
  <span class="value">+1-250-555-2135</span>
</div>

This will display something like:

work: +1-250-555-2142
work toll free: +1-800-555-1855
work fax: +1-250-555-2135

The list of tel types are: voice [which is the default if "type" is unspecified], home, msg, work, pref, fax, cell, video, pager, bbs, modem, car, isdn, pcs. As shown in the last example above, a tel may have multiple types. See hCard: Type Subproperty Values for the official list.

Photographs

Mark up representative image(s) of the person/org with the class name "photo", e.g.:

<img class="photo" src="http://www.factorycity.net/images/avatar.jpg" alt="" />

If your name is not already marked up (see the Names section above), and your first and last name consist of only two words, you can set the alt attribute for the image as your name. In this case, include the "fn" class name along with the "photo" class name in the class attribute:

<img class="photo fn" src="http://www.factorycity.net/images/avatar.jpg" alt="Chris Messina" />

To ensure that the picture is not left out whenever a hcard is converted into a vcard, the external URI should be replaced with the actual encoded picture data as follows:

<img alt="photo" class="photo" src="data:image/jpeg;base64,/9j/4AAQSkZJRgAB[...]RRxTwKpCP//Z" />

An easy way to encode a contact picture is to use some application which can export vcard files including contact picture, as the freeware Palm Desktop does.

Geographic Coordinates

Add your geographic coordinates:

<span class="geo">
  <span class="latitude">48.430092246</span>
  <span class="longitude">-123.364348450</span>
 </span>

A more human friendly version would be implemented as follows:

<div class="geo">
<abbr class="latitude" title="-31.388333">31&deg;23&#39;18&quot;S</abbr>, 
<abbr class="longitude" title="-57.960556">57&deg;57&#39;38&quot;O</abbr>
</div>

That will look like this: 31°23'18"S, 57°57'38"O.

Note that the degree, minute and seconds characters should go encoded as in the source code example above to prevent that the browser to confuses the character encoding used by the page and shows wrong characters, like chinese characters where accents should be displayed.

A good place to get your coordinate values in both formats is Wikipedia. Look for the article on your city and click the human friendly coordinates to load a page with the decimal values.

Fragments and linking

An hCard is a logical piece of content that people might like to link to. If it's on a page with other content, it can be hard to link to just the one hCard, unless you have a fragment identifier to use. In HTML, you can create fragment identifiers by adding an 'id' attribute to any element. It is good practice to add an 'id' attribute to an hCard, e.g.

<span id="my-hCard" class="vcard">
 <a class="url fn" href="http://suda.co.uk">
  Brian Suda
 </a>
</span>


Canonical hCard within a site

Nearly every social website has profile URLs for its members, typically with hCard.

Most of the pages on such websites link those canonical user profile URLs on the site itself with the icon and/or name the user. It makes sense to explicitly markup those links with both class names "url" and "uid", e.g. on a list of Twitter friends (note the additional use of the XOXO microformat) that might be hosted on Twitter itself:

<ul class="xoxo">
 <li class="vcard">
  <a class="url uid" href="http://twitter.com/briansuda">
   <img class="fn logo" src="b-icon.jpg" alt="Brian Suda" />
  </a>
 </li>
 <li class="vcard">
  <a class="url uid" href="http://twitter.com/pspmikek">
   <img class="fn logo" src="m-icon.jpg" alt="Michael Kaply" />
  </a>
 </li>
 <li>
  <a class="url uid" href="http://twitter.com/t">
   <img class="fn logo" src="t-icon.jpg" alt="Tantek Çelik" />
  </a>
 </li>
</ul>

Another example: event sites that list and link to user profiles of the people attending an event (e.g. Upcoming.org).

URL of an hCard being the page itself

The canonical hCard within a site (as noted above) often has hCard markup itself, and it's useful to markup the page itself as the URL for that hCard.

So how do you markup the URL of an hCard where the URL is the page itself?

A few variants have been observed in real-world publishing, each of which implies a solution:

  1. Profile self-hyperlinking with name/photo. Many (most?) hcard-supporting-user-profiles sites hyperlink the person's name (e.g. Myspace irhetoric) and/or image (e.g. Upcoming tantek) on their profile to the profile itself. This is a common design pattern. In this case the answer is obvious: simply add class="url uid" to the existing self-hyperlink.
  2. Profiles with a "profile" link and/or dynamic content. Some sites have a "Profile" navigation link which is clickable even on the profile itself (e.g. on Twitter login and go to your profile). In some cases the "Profile" link is highlighted among other navigation links to indicate that it's what is currently visible among the nav options (e.g. last.fm - login and go to your profile). Both of these sites have dynamic content on profile pages, and thus could also label such self-hyperlinks with text like "Reload" or "Refresh" - accurately indicating to the user that when they clicked the link, it wouldn't change the URL in their browser address bar, but would reload the page, likely visibly updating the page. In both these cases, the answer is the same as the first case above: simply add class="url uid" to the existing self-hyperlink.
  3. Profiles without apparent self-hyperlinks. Some sites' profile pages (e.g. Flickr tantek) have no self-hyperlink, possibly because their content is more static, and a visible self-hyperlink would appear to "do nothing" when clicked, either frustrating the user, or making them think the site was broken. For these sites, the author can include an empty hyperlink with an empty href attribute (which is resolved as a relative URL to the page itself) to provide an invisible hyperlink to the page itself which is thus both not typically clickable (since it takes up no space), nor has any content which could be erroneously read by a screen reader. E.g. <a class="url" href=""></a>. This authoring suggestion is probably good enough to handle this third, perhaps rarest case, though it would be useful to to have some test cases that can be run in various browsers / assistive technologies to see what they do. Another (lengthier) suggestion would be to use value-class-pattern value-title technique, e.g.: <span class="url uid"><span class="value-title" title="http://example.com/user/john"> </span></span>.

More tips and guidelines

Feel free to add more tips that experience has taught you while marking up hCards, even if all you add is a brief catch phrase that reminds you.

Related Pages

The hCard specification is a work in progress. As additional aspects are discussed, understood, and written, they will be added. These thoughts, issues, and questions are kept in separate pages.

hCard authoring tips was last modified: Wednesday, December 31st, 1969

Views