Microformats Wiki - User contributions [en]

User:AzulMarino

2007-12-05T11:56:09Z

AzulMarino:

See hcard and geo microformats implemented at [http://senda.miarroba.com my web site].

[http://mentoliptus.blogspot.com My blog] uses rel-tags.

hcard-implementations

2007-12-05T11:44:27Z

AzulMarino: /* Firefox extension */

<h1>hCard Implementations</h1>
{{TOC-right}}

This page is an '''informative''' section of the [[hcard|hCard specification]].

The following implementations have been developed which either generate or parse [[hcard|hCards]]. If you have such an hCard implementation, feel free to add it to '''the top''' of the New Implementations section. If you have a page or site which just ''publishes'' hCards, please use [[hcard-examples-in-wild]] instead.

== New Implementations ==
Add new implementations here for evaluation and classification into the below taxonomy of implementations.
* [[org.microformats.hCard]] - java hCard parser and creator.
* [http://mobileonlinebusiness.com.au/uf/vCard_to_hCard_converter.html Mobile Online Business' vCard to hCard converter]
*[http://www.jamplanet.com Jam] is an active address book extension for Firefox/Flock. Jam imports Vcard and various CSV formats, and can output contacts in Vcard and hCard format.
*The "[http://typo3.org/extensions/repository/view/tt_address/2.0.1/ tt_address]" extension for [http://www.typo3.com TYPO3] supports hCard since the latest release, v2.0.0
*[https://addons.mozilla.org/firefox/4106/ Operator] lets you combine pieces of information on Web sites with applications in ways that are useful. (Firefox-plugin)
*[http://rafaeloliveira.net/labs/hcard_creator.zip Wordpress hCard Creator] - I've made this simple plugin for wordpress. It adds the hCard Options submenu at Options menu, where you can create a simple hCard and put it on your blog using < ?php hcard_creator() ?> to show it. Also, it is possible to show an "export to vCard" link, which uses Brian Suda X2V. (Got send an e-mail to him regarding this)
*[http://www.alexa.com/site/devcorner/hcard Alexa hcard search]
*[http://leftlogic.com/lounge/articles/microformats_bookmarklet/ Microformats Bookmarklet] is a bookmarklet designed for IE6 and IE7, Firefox, Safari, Opera and Camino, that overlays on the current page to allow users to import individual hCards or hCalendars. Written by Remy Sharp.
*[http://domanske.de/2006/09/vcardexplorer-04/ vCardExplorer] is a Mac OS X Application, that displays VCF-Files and extracts hCards from Websites written by [http://vcardexplorer.corefault.de Daniel Kagemann].
* [http://placenamehere.com/mf/nnwextract/ Extract Microformats] is a script for NetNewsWire that supports extracting hCard and hCalendar data in blog posts (via technorati service). Written by [[User:ChrisCasciano|Chris Casciano]]
* [http://allinthehead.com/hkit/ hKit] is an open source PHP 5 parsing library with support for hCard.
* [http://kitchen.technorati.com/search Technorati Microformats Search] indexes [[hcard|hCard]], [[hcalendar|hCalendar]], and [[hreview|hReview]] as [http://tantek.com/log/2006/05.html#d31t1802 announced by Tantek].
** list of pages with indexing Issues so they can be looked into as to why data is not being extracted
** suda.co.uk/contact
** multipack.co.uk
* [http://www.webstandards.org/action/dwtf/microformats/ Dreamweaver Extension suite] from the [http://webstandards.org/ Web Standards Project] enables the authoring of hCards from within Dreamweaver 8.
* [http://scooch.gr0w.com/ Scooch] is a slide show and presentation creator that generates a [[hCard]] for individual slide show authors and comment authors with a CSS button to parse and download via [http://suda.co.uk/projects/X2V/ X2V]. Also uses [[hReview]] for slide ratings and [[rel-tag]] for categories.
* [http://blog.codeeg.com/2006/03/20/flock-tails-flocktails/ Flocktails] - port of Tails extension for Flock 0.5.12 that looks for hCards, hCalendar, xFolk and hReview and tosses them into a handy topbar
*[http://opensource.reevoo.com/2006/03/08/release-uformats-12/ uformats] is a ruby library that can parse [[hCalendar]], [[hCard]], [[hReview]] and [[rel-tag]]
* [http://blog.codeeg.com/tails-firefox-extension-03/ Tails] is a Firefox Extension that will display the presence and details of microformats ([[hcard|hCard]], [[hcalendar|hCalendar]], [[hreview|hReview]], [[xfolk|xFolk]]) on a webpage. [https://addons.mozilla.org/firefox/2240/ Tails Export] is an extended version.
* [http://www.stripytshirt.co.uk/features/firefox/smartzilla Smartzilla is a Firefox Extension] that finds hCards on web pages and lets you add them to your addressbook.
* [http://placenamehere.com/TXP/pnh_mf/ pnh_mf] is a plugin for [http://textpattern.com/ Textpattern] that supports embedding hCard and other microformats in templates and blog posts. Written by [http://placenamehere.com/ Chris Casciano].
* There is [http://flickr.com/photos/factoryjoe/68755089/ evidence of built-in hCard support in the Konqueror browser]. Specifically, Konqueror 3.5, in KDE 3.5 (kubuntu Breezy w/ update).
* There is [http://tagcamp.org/index.cgi?ContactList evidence of a kwiki plugin for hCards]. Update: the [http://svn.kwiki.org/cwest/Kwiki-hCard/ hCard kwiki plugin svn repository]. See the [http://microwiki.caseywest.com/index.cgi?hCard documentation of the hCard kwiki plugin].
* [http://suda.co.uk/projects/X2V/ X2V] is a bookmarklet that parses hCard and produces a .vcf (vCard) stream. Note: needs to be updated as the spec is refined.
* [http://www.stripytshirt.co.uk Duncan Walker] has built [http://www.stripytshirt.co.uk/features/firefox/smartzilla a Firefox extension] that gets hCard data from a webpage, uses Brian Suda's XSL (locally) to transform it to vcard format and opens the resulting .vcf file.
* [http://george.hotelling.net/90percent/ George] has written a [http://george.hotelling.net/90percent/geekery/greasemonkey_and_microformats.php Greasemonkey user script] that detects hCards and allows users to easily add them to their address book application. Relies on the X2V web service to do the conversion.
* [http://inside.glnetworks.de/ Martin Rehfeld] has updated the work of [http://blogmatrix.blogmatrix.com/ David Janes] and produced a [[Greasemonkey]] [http://inside.glnetworks.de/2006/06/05/microformats-have-arrived-in-firefox-15-greasemonkey-06/ script] that finds many microformat elements, including hCards, and [http://blog.davidjanes.com/mtarchives/2005_08.html#003379 provides a popup menu of actions]. The hCard to vCard conversion is done internally within the script. ''This will work with FireFox 1.5+/GreaseMonkey 0.6.4+ now.''
* [http://diveintomark.org/ Mark Pilgrim] has also written an [http://diveintomark.org/projects/greasemonkey/hcard/ hCard parser Greasemonkey user script]. It is self-contained and does not rely on the X2V web service.
* [http://www.oliverbrown.me.uk/2005/09/03/a-working-microformats-extension-to-simplexml/ Oliver Brown] has written an "extension" to [http://www.php.net/simplexml SimpleXML] that gives simple access to hCard information in PHP 5.
* [http://thedredge.org/ Andrew D. Hume] has built a system (Wordpress plugin?) for [http://thedredge.org/2005/06/using-hcards-in-your-blog/ using hCards in your blog] to represent people leaving comments on blog posts.
* [http://greenbytes.de/tech/webdav/rfc2629.xslt rfc2629.xslt] now attempts to generate hCard information ([http://ietf.org/rfc/rfc2629 RFC2629] is an XML format for authoring RFCs and Internet Drafts, see [http://greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html example document])
* [http://tantek.com/microformats/buddylist2hcards.html iChat buddy list to hCards] - Open source AppleScript to automatically convert one's buddy list in the MacOSX iChat AIM client into a valid XHTML 1.0 Strict list of hCards.
* [http://dev.w3.org/cvsweb/2001/palmagent/ palmagent] is a collection of palmpilot and sidekick tools. It includes X2V derivatives xhtml2hcard.xsl and toICal.xsl plus some [http://dev.w3.org/cvsweb/2001/palmagent/hcardTest.html hcardTest] materials
* [http://www.openpsa.org/ OpenPsa 2.x] CRM application uses hCard for all person listings. The widget is [http://www.midgard-project.org/midcom-permalink-922834501b71daad856f35ec593c7a6d reusable across Midgard CMS]
* [http://www.metonymie.com Emiliano Martínez Luque] has written an experimental [http://www.metonymie.com/hCard_extract/app.html hCard finder and structured search application] that finds hCards within a given set of URLs and returns the ones that match the specified search criteria.


==Authoring==
Implementations you can use to author, create, and publish hCards.

===Web-based Creators===
;hCard Creator : [http://microformats.org/code/hcard/creator hCard creator] ([[hcard-creator-feedback|hCard creator feedback]]) - create your own hCards.
; ... :

===Blogging and CMS tools===
;Textpattern plug-in :
[http://euphemize.net/blog/plugins/textpattern/jmc_event_manager/ jmc_event_manager] is a plugin for [http://textpattern.com/ Textpattern] that outputs locations and events in hCard (and hCalendar) formats. Written by [http://euphemize.net/ Joel Courtney].
; ... :

===Browser scripts and plug-ins===
Browser plugins that work with existing authoring tools:
; Any browser with javascript and a little bit of CSS : [http://microformats.org/code/hcard/creator microformats.org hCard creator] (see also [http://tantek.com/ Tantek]'s original [http://tantek.com/microformats/hcard-creator.html hCard creator on tantek.com].

===Desktop Authoring Tools===
* ...

==Search and Discovery==
* [http://kitchen.technorati.com/search Technorati Microformats Search] indexes [[hcard|hCard]], [[hcalendar|hCalendar]], and [[hreview|hReview]] as [http://tantek.com/log/2006/05.html#d31t1802 announced by Tantek].
* [http://leftlogic.com/info/articles/microformats_bookmarklet Microformats Bookmarklet] is a bookmarklet designed for Safari (works in Firefox and Camino) that overlays on the current page to allow users to import individual [[hcard|hCards]] or [[hcalendar|hCalendars]]. Written by [http://leftlogic.com Remy Sharp].



==Conversion and Import==
Implementations you can use to importing into an address book application, typically by converting hCard to vCard.

===Web Services===
These return vCard (.vcf) and other contact formats for easy importing into typical address book programs or other processing.
* [http://www.tomota.de www.tomota.de] Online address book that allows to import, export and convert hCard into vCard, ldif, csv and plain text.

* ...

===Firefox Greasemonkey Plugins===
* ...

===Aggregators===
* ...

==Browsing==
Implementations that detect, display and otherwise highlight hCards in pages.
* ...

===Firefox extension===

[http://www.kaply.com/weblog/operator Operator] - This extension is casual-user, advanced-user and developer friendly. Very customizable and unobstrusive.

===Flock extension===
* ...

==Open Source==
Open source libraries of hCard parsers and other related code for building hCard implementations. Note: it is very likely that above implementations may be duplicated in this section. That's ok.
* ...
;Javascript
: The [http://microformats.org/code/hcard/creator hCard creator] ([[hcard-creator-feedback|hCard creator feedback]]) is a very simple, yet illustrative, open source user interface / form / script which creates an hCard in real-time as you type in a set of contact information.

; PHP :
* [[hKit]]
; Java :
* [[org.microformats.hCard]]
; Ruby :
: ...
; XSLT :
* ...

== Additional Applications ==
This section should probably be incorporated into [[hcard-brainstorming]].

There are numerous potential additional uses and applications for hCards on the Web. The following are merely a few thoughts and possibilities that folks have come up with:

* As an open standard/format for [http://www.gravatar.com/ Gravatars].
** Like [http://alper.nl/cgi-bin/OpenAvatar.py?url=http://tantek.com this].
** Wordpress plugin with hCard based replacement for gravatar is in the make. [[User:Alper|Alper]] 12:59, 8 Aug 2007 (PDT)
* Marking up individual authors of blog posts on a group blog
* Marking up people's names and URLs in a blogroll
* Any reference to people in blog posts (e.g. when citing them, or referencing them, or describing them, by name).
* ...

== Related Pages ==
{{hcard-related-pages}}

hcard-authoring

2007-12-05T11:30:04Z

AzulMarino: /* Add To Address Book Links */ tip for index pages

<h1>hCard authoring</h1>
{{TOC-right}}
This page contains useful tips and guidelines for how to author [[hcard|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):''' [[User:Tantek|Tantek Çelik]], [[User:MarkRickerby|Mark Rickerby]]

== 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:

<pre>
<nowiki>
<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>
</nowiki>
</pre>

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]]:

<pre><nowiki>
<div id="contact" class="vcard">
</nowiki></pre>

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:

<pre><nowiki>
<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>
</nowiki></pre>

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]]:

<pre><nowiki>
<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>
</nowiki></pre>

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.

== Creating new hCards ==
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.

== 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 "[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.

=== 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 "<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).

E.g.
<pre><span class="foo">...</span></pre>
would become:
<pre><span class="foo xyz">...</span></pre>

And
<pre><span>...</span></pre>
would become:
<pre><span class="xyz">...</span></pre>

=== 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 <code><nowiki><dfn></nowiki></code> 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 "<code>vcard</code>" to that element.

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 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.
<pre><nowiki><div class="vcard"><span class="fn">Rohit Khare</span></div></nowiki></pre>

For people with middle names (e.g. "Håkon Wium Lie"), or with multi-word last names (e.g. "Thomas Vander Wal"), you must mark them up with the "n" property and its sub-properties "given-name" and "family-name", e.g.:
<pre><nowiki>
<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>

<div class="vcard"><span class="fn n">
<span class="given-name">Thomas</span>
<span class="family-name">Vander Wal</span>
</span></div>
</nowiki></pre>

==== 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.
<pre><nowiki><div class="vcard"><span class="fn org">Technorati</span></div></nowiki></pre>

=== Representative URLs ===
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.

Blogrolls are a good example of this (see also [[xoxo|XOXO]]).

Since the class attribute takes a space separated set of class names, one can often markup the URL on the same element as the name, e.g.
<pre><nowiki><span class="vcard"><a href="http://theryanking.com" class="fn url">Ryan King</a></span></nowiki></pre>

Markup as many URLs as you have for the person/org with the class name "<code>url</code>", e.g. URLs to social network and other online service profiles.

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.

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

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>.

View source on the [http://tantek.com/microformats/2006/03-01-TechPlenAgenda.html 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 <code><nowiki><span class="note">...</span></nowiki></code> elements. You can have more than one; converters will simply append them all in source order.

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.

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 [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.

=== Set the lang when different ===
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.

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

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.

=== Phone Numbers ===
Add a few phone numbers like this:
<pre>
<div class="tel">
<span class="type">work</span>
tel: <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>
fax: <span class="value">1-250-555-2135</span>
</div>
</pre>

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.

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

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

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:

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

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:

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

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.

=== Geographic Coordinates ===
Add your geographic coordinates:
<pre>
<span class="geo">
<span class="latitude">48.430092246</span>
<span class="longitude">-123.364348450</span>
</span>
</pre>

A more human friendly version would be implemented as follows:

<pre>
<div class="geo">
<abbr class="latitude" title="-31.388333">31°23'18"S</abbr>,
<abbr class="longitude" title="-57.960556">57°57'38"O</abbr>
</div>
</pre>

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' to the wrapper element for an hCard.

=== 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
* ...

== 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 for the convenience of your users.

Here is an example of such a link:

<pre><nowiki>
<a href="http://feeds.technorati.com/contacts/http://tantek.com/%23hcard">
Add to Address Book
</a>
</nowiki></pre>

Simply substitute the link to your hCard for the http://tantek.com/%23hcard URL above, and if you have more than one hCard on that page, you should put a unique ID on each, and then substitute %23hcard in the example URL with %23THEID in your href code where THEID is the ID attribute value that you put on the hCard you are creating the link for.

If a single hcard is served by an index page like http://foo.com/index.php, you just need to substitute http://tantek.com/%23hcard with http://foo.com/

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

== Related Pages ==
{{hcard-related-pages}}

hcard-authoring

2007-12-05T11:21:43Z

AzulMarino: /* Geographic Coordinates */ human friendly

<h1>hCard authoring</h1>
{{TOC-right}}
This page contains useful tips and guidelines for how to author [[hcard|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):''' [[User:Tantek|Tantek Çelik]], [[User:MarkRickerby|Mark Rickerby]]

== 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:

<pre>
<nowiki>
<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>
</nowiki>
</pre>

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]]:

<pre><nowiki>
<div id="contact" class="vcard">
</nowiki></pre>

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:

<pre><nowiki>
<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>
</nowiki></pre>

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]]:

<pre><nowiki>
<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>
</nowiki></pre>

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.

== Creating new hCards ==
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.

== 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 "[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.

=== 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 "<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).

E.g.
<pre><span class="foo">...</span></pre>
would become:
<pre><span class="foo xyz">...</span></pre>

And
<pre><span>...</span></pre>
would become:
<pre><span class="xyz">...</span></pre>

=== 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 <code><nowiki><dfn></nowiki></code> 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 "<code>vcard</code>" to that element.

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 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.
<pre><nowiki><div class="vcard"><span class="fn">Rohit Khare</span></div></nowiki></pre>

For people with middle names (e.g. "Håkon Wium Lie"), or with multi-word last names (e.g. "Thomas Vander Wal"), you must mark them up with the "n" property and its sub-properties "given-name" and "family-name", e.g.:
<pre><nowiki>
<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>

<div class="vcard"><span class="fn n">
<span class="given-name">Thomas</span>
<span class="family-name">Vander Wal</span>
</span></div>
</nowiki></pre>

==== 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.
<pre><nowiki><div class="vcard"><span class="fn org">Technorati</span></div></nowiki></pre>

=== Representative URLs ===
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.

Blogrolls are a good example of this (see also [[xoxo|XOXO]]).

Since the class attribute takes a space separated set of class names, one can often markup the URL on the same element as the name, e.g.
<pre><nowiki><span class="vcard"><a href="http://theryanking.com" class="fn url">Ryan King</a></span></nowiki></pre>

Markup as many URLs as you have for the person/org with the class name "<code>url</code>", e.g. URLs to social network and other online service profiles.

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.

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

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>.

View source on the [http://tantek.com/microformats/2006/03-01-TechPlenAgenda.html 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 <code><nowiki><span class="note">...</span></nowiki></code> elements. You can have more than one; converters will simply append them all in source order.

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.

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 [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.

=== Set the lang when different ===
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.

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

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.

=== Phone Numbers ===
Add a few phone numbers like this:
<pre>
<div class="tel">
<span class="type">work</span>
tel: <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>
fax: <span class="value">1-250-555-2135</span>
</div>
</pre>

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.

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

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

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:

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

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:

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

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.

=== Geographic Coordinates ===
Add your geographic coordinates:
<pre>
<span class="geo">
<span class="latitude">48.430092246</span>
<span class="longitude">-123.364348450</span>
</span>
</pre>

A more human friendly version would be implemented as follows:

<pre>
<div class="geo">
<abbr class="latitude" title="-31.388333">31°23'18"S</abbr>,
<abbr class="longitude" title="-57.960556">57°57'38"O</abbr>
</div>
</pre>

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' to the wrapper element for an hCard.

=== 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
* ...

== 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 for the convenience of your users.

Here is an example of such a link:

<pre><nowiki>
<a href="http://feeds.technorati.com/contacts/http://tantek.com/%23hcard">
Add to Address Book
</a>
</nowiki></pre>

Simply substitute the link to your hCard for the http://tantek.com/%23hcard URL above, and if you have more than one hCard on that page, you should put a unique ID on each, and then substitute %23hcard in the example URL with %23THEID in your href code where THEID is the ID attribute value that you put on the hCard you are creating the link for.

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

== Related Pages ==
{{hcard-related-pages}}

hcard-authoring

2007-12-05T11:12:20Z

AzulMarino: /* Photographs */ Picture are data

<h1>hCard authoring</h1>
{{TOC-right}}
This page contains useful tips and guidelines for how to author [[hcard|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):''' [[User:Tantek|Tantek Çelik]], [[User:MarkRickerby|Mark Rickerby]]

== 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:

<pre>
<nowiki>
<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>
</nowiki>
</pre>

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]]:

<pre><nowiki>
<div id="contact" class="vcard">
</nowiki></pre>

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:

<pre><nowiki>
<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>
</nowiki></pre>

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]]:

<pre><nowiki>
<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>
</nowiki></pre>

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.

== Creating new hCards ==
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.

== 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 "[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.

=== 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 "<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).

E.g.
<pre><span class="foo">...</span></pre>
would become:
<pre><span class="foo xyz">...</span></pre>

And
<pre><span>...</span></pre>
would become:
<pre><span class="xyz">...</span></pre>

=== 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 <code><nowiki><dfn></nowiki></code> 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 "<code>vcard</code>" to that element.

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 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.
<pre><nowiki><div class="vcard"><span class="fn">Rohit Khare</span></div></nowiki></pre>

For people with middle names (e.g. "Håkon Wium Lie"), or with multi-word last names (e.g. "Thomas Vander Wal"), you must mark them up with the "n" property and its sub-properties "given-name" and "family-name", e.g.:
<pre><nowiki>
<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>

<div class="vcard"><span class="fn n">
<span class="given-name">Thomas</span>
<span class="family-name">Vander Wal</span>
</span></div>
</nowiki></pre>

==== 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.
<pre><nowiki><div class="vcard"><span class="fn org">Technorati</span></div></nowiki></pre>

=== Representative URLs ===
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.

Blogrolls are a good example of this (see also [[xoxo|XOXO]]).

Since the class attribute takes a space separated set of class names, one can often markup the URL on the same element as the name, e.g.
<pre><nowiki><span class="vcard"><a href="http://theryanking.com" class="fn url">Ryan King</a></span></nowiki></pre>

Markup as many URLs as you have for the person/org with the class name "<code>url</code>", e.g. URLs to social network and other online service profiles.

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.

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

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>.

View source on the [http://tantek.com/microformats/2006/03-01-TechPlenAgenda.html 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 <code><nowiki><span class="note">...</span></nowiki></code> elements. You can have more than one; converters will simply append them all in source order.

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.

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 [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.

=== Set the lang when different ===
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.

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

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.

=== Phone Numbers ===
Add a few phone numbers like this:
<pre>
<div class="tel">
<span class="type">work</span>
tel: <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>
fax: <span class="value">1-250-555-2135</span>
</div>
</pre>

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.

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

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

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:

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

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:

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

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.

=== Geographic Coordinates ===
Add your geographic coordinates:
<pre>
<span class="geo">
<span class="latitude">48.430092246</span>
<span class="longitude">-123.364348450</span>
</span>
</pre>

=== 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' to the wrapper element for an hCard.

=== 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
* ...

== 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 for the convenience of your users.

Here is an example of such a link:

<pre><nowiki>
<a href="http://feeds.technorati.com/contacts/http://tantek.com/%23hcard">
Add to Address Book
</a>
</nowiki></pre>

Simply substitute the link to your hCard for the http://tantek.com/%23hcard URL above, and if you have more than one hCard on that page, you should put a unique ID on each, and then substitute %23hcard in the example URL with %23THEID in your href code where THEID is the ID attribute value that you put on the hCard you are creating the link for.

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

== Related Pages ==
{{hcard-related-pages}}