hCard FAQ

(Difference between revisions)

Jump to: navigation, search
(Added reference to the difference between GEO Point and ADR polygon)
Current revision (18:32, 15 March 2015) (view source)
(Can you mix properties and the root class name: wikilink)
 
(102 intermediate revisions not shown.)
Line 1: Line 1:
-
= hCard FAQ =
+
<entry-title> hCard FAQ </entry-title>
-
This page is for documenting Q&A about [[hcard|hCard]].  If you have a new question to ask, Please consider first asking your question on the [http://microformats.org/mailman/listinfo/microformats-discuss/ microformats-discuss] list.
+
This documents frequently asked questions and answers (FAQs) about [[hcard|hCard]].  For FAQs regarding microformats in general, or across microformats, see the [[faq|microformats FAQ]].
-
== Q&A ==
+
If you have a new question to ask, please consider first asking your question on the [irc://irc.freenode.net/#microformats microformats irc channel] (preferably) or the [http://microformats.org/mailman/listinfo/microformats-discuss/ microformats-discuss] mailing list.  New questions and answers should be added to the end of the list.  If you have a new question but not an answer, please add it to [[hcard-issues|hCard issues]].
-
# ''Should I use the more semantic <address> element for my hCards?''
+
<h2>Editing this Page</h2>
-
#* Yes the <address> element is more semantic, but it is ''too'' specifically semantic for most hCard uses. The poorly named <address> element really means <contact-info-for-this-web-page>.  The [http://www.w3.org/TR/html401/struct/global.html#h-7.5.6 HTML4 definition of the ADDRESS element] says it is used "to supply contact information for a document or a major part of a document such as a form." Therefore <address> should be used for an hCard ONLY IF that hCard represents the contact information for the page or major part thereof.  One example of such a usage is on [http://tantek.com/log/ Tantek's blog]. Another way of saying this is the following two statements: Every <address> on a page SHOULD be an hCard. But not every hCard should be an <address>.
+
Please do not use "?" or other punctuation in the headers - it helps to keep the URLs to their fragment identifiers shorter and easier to read, copy/paste etc.  See [[how-to-play]] for more wiki editing guidelines.
-
# ''Why is it necessary to put class name "url" on URL elements in the hCard when those hyperlinks already start with "http://", and that is enough to distinguish them from email links?''
+
 
-
#* The classname "url" is necessary to explicitly distinguish hyperlinks that are URL elements for the hCard, from email hyperlinks, as well as hyperlinks to photos, or other random hyperlinks that happen to be inside the hCard.
+
<h2> Q&A </h2>
-
# ''I already have a vCard that I keep up-to-date. I don't want to change any references to it because it might break something else, what can I do?''
+
=== What is the point of hCard ===
-
#* You can use .HTACCESS to rewrite links to your vCard to a webservice that converts a page to the vCard dynamically, to do this you need to add something similar to your .htaccess file
+
''What is the point of hCard to people, businesses, etc.?''
-
<pre>
+
* hCard helps people publish up-to-date contact details (e.g. see [http://24ways.org/2008/a-christmas-hcard-from-me-to-you A Christmas hCard From Me To You] for how to do so as a greeting card)
-
RewriteRule ^path/to/old.vcf http://suda.co.uk/projects/X2V/get-vcard.php\?uri=http://example.com/hCard_encoded.htm&filename=old.vcf
+
* hCards help businesses: [http://www.clagnut.com/blog/2244/ Microformats for business owners]
-
</pre>
+
* hCards help with SEO:
 +
** [http://searchengineland.com/the-hcard-microformat-local-search-optimization-12424 search engine land: The hCard Microformat and Local Search Optimization]
 +
** [http://www.naturalsearchblog.com/archives/2006/09/28/tips-for-local-search-engine-optimization-for-your-site/ natural search blog: Tips for Local Search Engine Optimization for Your Site]
 +
* content marked up with hCard can be converted to vCards by spiders and other aggregators, and can be used in vCard application and services. [http://www.ablognotlimited.com/articles/getting-semantic-with-microformats-part-3-hcard/ Getting Semantic With Microformats, Part 3: hCard]
 +
 
 +
=== How is hCard different than just links ===
 +
''How is hCard different than just links?''
 +
* hCard can be used to express that a name and a link (and potentially additional information) are semantically connected and refer to a specific person, place, or organization.
 +
 
 +
=== How does hCard help users ===
 +
''How does hCard help users, e.g. how does it improve the user experience in browsers more than just providing name and email as text?''
 +
* In most browsers (e.g. [[Flock]], [[Firefox]], [[Internet Explorer]], [[Safari]] with various plugins), users can detect when there are hCards (or other common microformats) on a page, and easily download that hCard contact info in its entirety, rather than having to copy and paste each individual name, email address, link etc.
 +
* See also: [[user-interface#Browser_Integration|Browser Integration]]
 +
 
 +
=== How can I style hCards with CSS ===
 +
''How can I style hCard with CSS?''
 +
* [http://24ways.org/2006/styling-hcards-with-css 24 ways: Styling hCards with CSS]
 +
* [http://dev.opera.com/articles/view/introduction-to-hcard-part-two-styling/ Introduction to hCard, Part two: Styling hCards]
 +
* [http://24ways.org/2008/a-christmas-hcard-from-me-to-you 24 ways: A Christmas hCard From Me To You]
 +
 
 +
=== How do I convert hCards to vCards for download on a site ===
 +
''Is there any live way to convert hCards to vCards for download on a site? In other words, I have added hCard to my page, but i'd like my users to have a 'download vCard' button.''
 +
* Short answer, use the [[H2VX]] hCard to vCard service in a hyperlink, e.g.:
 +
<source lang=html4strict><a href="http://h2vx.com/vcf/YOURURLHERE">download vCard</a></source>
 +
Consider using more user-friendly text as well, like '''Add to Address Book'''.
 +
There are many examples of this in the [[hcard-examples-in-wild|hCard Examples in the Wild]] page.  Note that the [[H2VX]] hCard to vCard service is based on the open source XSLT "[[X2V]]" by Brian Suda and others.  If you want, you can install X2V yourself and run your own local converter.
 +
 
 +
=== Should I use ADDRESS for hCards ===
 +
''Should I use the more semantic <code><nowiki><address></nowiki></code> element for my hCards?''
 +
* The <code><nowiki><address></nowiki></code> element is more semantic, but it is ''too'' specifically semantic for most hCard uses. The poorly named <code><nowiki><address></nowiki></code> element really means <contact-info-for-this-web-page>.  The [http://www.w3.org/TR/html401/struct/global.html#h-7.5.6 HTML4 definition of the ADDRESS element] says it is used "to supply contact information for a document or a major part of a document such as a form." Therefore, <code><nowiki><address></nowiki></code> should be used for an hCard ONLY IF that hCard represents the contact information for the page or major part thereof.  One example of such a usage is on [http://tantek.com/ Tantek's blog]. Another way of saying this is the following two statements: Every <address> on a page SHOULD be an hCard. But not every hCard should be an <code><nowiki><address></nowiki></code>. <br /> In short, <strong>DO NOT</strong> use <code><nowiki><address></nowiki></code> to markup physical/street/mailing addresses in general.  Only use it to markup the <em>contact information for the page</em> (or major part thereof), and when doing so, use it to markup <em>the entire</em> contact information (via &lt;address class="vcard"&gt;), not just a physical/street/mailing address for the contact.
 +
 
 +
For more on different types of significant hCards for pages, and semantics distinctions among them, see [[hcards-and-pages]].
 +
 
 +
=== Why is adr property necessary ===
 +
''What is the point of class="adr" when we have the <address> element?.''- 2006-12-04 asked by [[User:JoshieSurber|Joshie]] [http://joshie.surber.us Surber].
 +
* First, '''<address> DOES NOT MEAN "address"''', please read [[hcard-faq#Should_I_use_ADDRESS_for_hCards|previous FAQ answer first and thoroughly]]! Second, "adr" is about physical addresses, whereas <address> is meant specifically for the contact information for the page or major part thereof.  They are totally different.
 +
 
 +
=== Why is url property necessary ===
 +
''Why is it necessary to put class name "url" on URL elements in the hCard when those hyperlinks already start with "http://", and that is enough to distinguish them from email links?''
 +
* The classname "url" is necessary to explicitly distinguish hyperlinks that are URL elements for the hCard, from other hyperlinks that may be related to the item or otherwise in the same containing element but should not be included in the hCard. Common links that may appear in the document but not be contact information are action related links (download data, add to friends list, etc.) contact hyperlinks (email, internal site messaging, autodialers), as well as hyperlinks to photos, or other random hyperlinks that happen to be inside the hCard.
 +
 
 +
=== Can an hCard have multiple URLs ===
 +
''Can an hCard have multiple URLs?''
 +
 
 +
* Yes hCards may have multiple URLs. Note that "url" is not one of the [[hcard-singular-properties]].
 +
 
 +
=== I have a problem with serving a vCard vcf file ===
 +
''I have a problem with serving a vCard .vcf file that has the info from my /contact/ page from my website. E.g. browsers just display the text of the vCard .vcf file instead of downloading it.''
 +
 
 +
The easiest thing to do and support (especially with more and more vCard consumers out there with their own quirks) is to:
 +
 
 +
# [[hcard-authoring|Add hCard markup]] to your /contact/ page where you already have your contact info visible in the content.  See also the [http://microformats.org/code/hcard/creator/ hCard creator] which is a useful tool for learning how hCard markup works.
 +
# Change the link to your vCard .vcf file to point to: <nowiki>http://h2vx.com/vcf/http://yourwebsite.example.com/contact/</nowiki>
 +
 
 +
This way you won't have to worry about duplicate data either - just update the content on your contact page marked up in hCard and anyone that gets your vCard will automatically get your updated info without you having to worry about updating separate file.
 +
 
 +
=== How do I support an existing vCard URL ===
 +
''I already have a vCard that I keep up-to-date. I don't want to change any references to it because it might break something else, what can I do?''
 +
* You can use .HTACCESS to rewrite links to your vCard to a webservice that converts a page to the vCard dynamically, to do this you need to add something similar to your .htaccess file
 +
<source lang=text>
 +
RewriteRule ^path/to/old.vcf http://h2vx.com/vcf/http://example.com/hCard_encoded.htm&filename=old.vcf
 +
</source>
Now you shouldn't have to do anything else, all links to the "old.vcf" are redirected to the webservice and will return a new vCard that is dynamially generated from your page.
Now you shouldn't have to do anything else, all links to the "old.vcf" are redirected to the webservice and will return a new vCard that is dynamially generated from your page.
I think that using 'Redirect' is better than using mod_rewrite (is not enabled on some hosts) --Robert Bachmann
I think that using 'Redirect' is better than using mod_rewrite (is not enabled on some hosts) --Robert Bachmann
-
<pre>
+
<source lang=text>
-
Redirect /path/to/old.vcf http://suda.co.uk/projects/X2V/get-vcard.php?uri=http://example.com/hCard_encoded.htm&filename=old.vcf
+
Redirect /path/to/old.vcf http://h2vx.com/vcf/http://example.com/hCard_encoded.htm&filename=old.vcf
-
</pre>
+
</source>
-
<ol start="4"><li>''Is there a list of all hCard properties which can be plural?</li>
+
-
* We have avoided *duplicating* (or providing a shortcut for) the "can this property occur multiple times or not" deliberately in order to avoid repeating a constraint from RFC 2426 vCard, and thus potentially getting it wrong.  Here is the way to determine whether or not a particular property can occur multiple times (is a plural property / may have multiple instances or values).
+
-
*# Check the [[hcard-profile|hCard XMDP profile]] for the property definition.
+
-
*# If the property definition references a plural form in RFC 2426 (e.g. honorific-suffix references honorific suffixes), then the property is a plural property.
+
-
*# Else go check the referenced section in RFC 2426 which should state explicitly whether or not the property is plural or singular.
+
-
*# Else (if RFC 2426 is *not* explicit) then the property is plural.
+
-
</ol>
+
-
<ol start="5"><li>''What does FN stand for?''
+
=== Why does my hCard photo not show up in Address Book ===
 +
''Why are photos not working for me when I import my hCard as a vCard into the Apple Address Book?''
 +
 
 +
* The Apple Address Book does not support PHOTO properties that have URL values. This is a [[vcard-implementations#AAB_PHOTO|known shortcoming/bug in the Apple Address Book]] implementation. We encourage you to file a bug/feature request with Apple to add support for the vCards with PHOTO properties that have URL values to the Apple Address Book.
 +
 
 +
=== Why does hCard use <code>vcard</code> as the root class name ===
 +
[[hcard|hCard]] maps the properties and values of the vCard standard ([http://www.ietf.org/rfc/rfc2426.txt RFC2426]), hence the use of the <code>vcard</code> class name inside the HTML markup. More background on the reasons behind that decision here: [[hcard-parsing#root_class_name|hCard Parsing: Root Class Name]].
 +
 
 +
=== What are plural hCard properties ===
 +
''Is there a list of all hCard properties which can be plural?''<br />
 +
''Is there a list of all the properties which can have multiple instances?''
 +
* There is the [[hcard#Property_List|list of hCard properties]], and the list of [[hcard#Singular_properties|singular hCard properties]]. Everything that is not singular is plural.  This list was presented explicitly (after much analysis of RFC2426) because it was too hard to read RFC2426 and reliably grok which properties were singular vs. plural. See also [[hcard-cheatsheet]].
 +
 
 +
=== How do you mark up an organization ===
 +
''How do I create an hCard for an organization or a company?''
 +
 
 +
Mark up hCards for organizations or companies by using both the "fn" and "org" properties for the name of the organization/company. E.g.
 +
<source lang=html4strict>
 +
<p class="vcard">You can help support
 +
<span class="fn org">microformats.org</span>
 +
by publishing microformats on your web pages,
 +
adding microformats support to your tools,
 +
giving constructive feedback on the wiki,
 +
and participating in discussions on IRC channel
 +
</p>
 +
</source>
 +
 
 +
See also: [[hcard-authoring#Organization_hCards|hCard authoring: Organization hCards]].
 +
 
 +
=== What does FN stand for ===
 +
''What does FN stand for?''
* FN stands for "Formatted Name." From Section 3.1.1 of the RFC:
* FN stands for "Formatted Name." From Section 3.1.1 of the RFC:
<blockquote>Type purpose: To specify the formatted text corresponding to the name of the object the vCard represents.</blockquote>
<blockquote>Type purpose: To specify the formatted text corresponding to the name of the object the vCard represents.</blockquote>
* The reasoning behind this seems to be that, while N gives us a structured name, FN gives us the human-readable, formatted name which is assembled from its structured parts in a culturally dependant way.
* The reasoning behind this seems to be that, while N gives us a structured name, FN gives us the human-readable, formatted name which is assembled from its structured parts in a culturally dependant way.
-
</li>
+
 
-
<li>''How do you represent gender in hCard?''
+
=== How do you mark up a first or last name ===
-
* There is no GENDER property in [http://www.ietf.org/rfc/rfc2426.txt vCard RFC2426]. [[hcard|hCard]] is following the schema from vCard for interoperability reasons. If you want, it is possible to represent gender implicitly in the honorific-prefix field, e.g. Mr. for male, and Ms. for female:
+
''I don't see anything for first/last names.''
-
<pre><nowiki>
+
 
 +
* "first" is a presentational culture-specific (non-l10n, non-18n) description (as is "last").
 +
* Hence vCard and hCard have <code>given-name</code> (and <code>family-name</code>), and [[h-card]] has <code>p-given-name</code> (and <code>p-family-name</code>).
 +
 
 +
See [[hcard-authoring#The_Importance_of_Names|hCard authoring: Importance of Names]] for examples.
 +
 
 +
=== How do you mark up a middle name or initial ===
 +
''How does one handle middle initials/names in hCard?''
 +
* Use the "additional-name" subproperty to markup a middle name.  For middle initials, use the <code>abbr</code> element to indicate that middle initial is an abbreviation, and use its <code>title</code> attribute for the expanded middle name if you have it. See [[hcard-authoring#middle-name|hCard authoring: middle name]] for examples.
 +
 
 +
=== How do you mark up suffixes ===
 +
''How does one handle suffixes, both family related and honorific?''
 +
* Use the "honorific-suffix" subproperty to markup both familial suffixes (e.g. Jr., Sr., II, III, etc.) and honorific suffixes (e.g. Ph.D., Esq., M.D., etc.).
 +
* e.g.
 +
<source lang=html4strict><abbr class="honorific-suffix" title="Junior">Jr.</abbr></source>
 +
 
 +
=== How do you mark up city state and zip ===
 +
''How do you mark up the city, state, and zip code of an address?''
 +
 
 +
* The terms city, state, and zip code tend to be a bit US and/or anglo-centric.
 +
* In vCard and hCard, there are the equivalents:
 +
** <code>locality</code> (city)
 +
** <code>region</code> (state or province)
 +
** <code>postal-code</code> (zip code)
 +
* and in [[h-card]]
 +
** <code>p-locality</code>
 +
** <code>p-region</code>
 +
** <code>p-postal-code</code>
 +
 
 +
=== How is gender represented ===
 +
''How do you represent gender in hCard?''
 +
 
 +
If you're using [[microformats2]]:
 +
* Use [[h-card]] and the properties <code>p-sex</code> and <code>p-gender-identity</code>.
 +
 
 +
If you're using [[hCard]]:
 +
* There is no GENDER property in [http://www.ietf.org/rfc/rfc2426.txt vCard3 RFC2426]. [[hcard|hCard]] is following the schema from vCard for interoperability reasons.  
 +
 
 +
It is possible to represent gender implicitly in the honorific-prefix field, e.g. Mr. for male, and Ms. for female:
 +
<source lang=html4strict>
<span class="honorific-prefix">Mr.</span>
<span class="honorific-prefix">Mr.</span>
-
</nowiki></pre>
+
</source>
or
or
-
<pre><nowiki>
+
<source lang=html4strict>
<span class="honorific-prefix">Ms.</span>
<span class="honorific-prefix">Ms.</span>
-
</nowiki></pre>
+
</source>
-
</li>
+
 
-
<li>''Is it OK for an hCard node to contain extra elements?''
+
This approach does have the limitation that "Mr." and "Ms." (or "Miss"/ "Mrs.") may conflict with a higher-ranking, gender-neutral honorific, such as "Dr."  or "Rev." for the person, as it is unusual to refer to someone as "Mr. Dr." or "Mrs. Rev." for example. See [[hcard-issues]].
 +
 
 +
See also the [[gender]] research page.
 +
 
 +
=== Can a hCard contain extra elements ===
 +
''Is it OK for an hCard node to contain extra elements?''
* Yes, parsers will ignore anything they don't understand.
* Yes, parsers will ignore anything they don't understand.
-
</li><li>Can I automatically add GEO from an address when transfominh an hCard to vCard if it is not present?
+
 
-
* No, an address represents a building which is a polygon, whereas a GEO only represents a single point</li>
+
=== Can a GEO be inferred from an ADR in an hCard ===
-
</ol>
+
''Can I automatically add GEO from an address when transforming an hCard to vCard if it is not present?''
 +
* No, an address represents an area of land which is a polygon (or perhaps a space in a building which is a polyhedron), whereas a GEO only represents a single point. They are not equivalent.
 +
 
 +
=== X2V does not convert email with name as plain text ===
 +
''X2V doesn't convert my email address correctly, it is in the form href="FirstName LastName &lt;Email@example.com&gt;"''
 +
* While that form of email address works for some programs such as outlook, it is not a valid mailto: value (see [http://www.faqs.org/rfcs/rfc2368.html RFC2368]) the FirstName and LastName should be omitted.
 +
 
 +
One possible valid hCard markup would be:
 +
 
 +
<source lang=html4strict>
 +
<span class="vcard">
 +
  <span class="fn">Firstname Lastname</span>
 +
&amp;lt;<a class="email" href="mailto:Email@example.com">Email@example.com</a>&amp;gt;
 +
</span>
 +
</source>
 +
 
 +
This might be displayed as:
 +
<div style="border: thin dashed black">
 +
Firstname Lastname &lt;[http://email@example.com email@example.com]&gt;
 +
</div>
 +
 
 +
=== What hCard properties are required ===
 +
''What properties are required in an hCard?''
 +
* The only required properties are 'fn' (the formatted name) and 'n' (the structured name), but 'n' can under certain circumstances be inferred from the <code>fn</code> property. See the [[hcard#Implied_.22n.22_Optimization|Implied N Optimization]] for details. See also [[hcard-cheatsheet]].
 +
 
 +
=== Does N property require all sub-properties ===
 +
''If I use the 'n' property, do I have to use ALL of the sub-properties?''
 +
* No, You can use as many or as few as you need to mark-up the name, but at a minimum you should at least use the 'given-name' and 'family-name' sub-properties if at all possible.  If all you have is a nickname/handle/userid, then consider simply marking it up as an 'fn' property and taking advantage of the [http://microformats.org/wiki/hcard#Implied_.22nickname.22_Optimization Implied "nickname" Optimization]. See also [[hcard-cheatsheet]].
 +
 
 +
=== Do FN and N need to be on same element ===
 +
''Do the 'fn' and 'n' properties have to be on the same element?''
 +
* No, you can have two separate elements, for example:
 +
<source lang=html4strict>
 +
<p class="vcard">My name is
 +
<span class="n">
 +
<span class="honorific-prefix">Mr.</span>
 +
<span class="given-name">John</span>
 +
<span class="additional-name">Q</span>
 +
<span class="family-name">Public</span>
 +
</span>
 +
but you can just call me
 +
<span class="fn">Johnny</span>
 +
</p>
 +
</source>
 +
 
 +
===Can FN be in a backwards order and N still extract the information correctly===
 +
''Can FN be in a backwards order and N still extract the information correctly?''
 +
* Yes, the FN value will take the text string as is, but N will look to the sub-properties and re-order then when converting them to vCard.
 +
<source lang=html4strict>
 +
<span class="fn n"><span class="family-name">Smith</span>,  <span
 +
class="given-name">John</span></span>
 +
</source>
 +
 
 +
The FN value would be "Smith, John", but the N value would correctly extract "John" as the given name, and "Smith" as the family name. This is useful for some cultures which reverse the name order.
 +
 
 +
The same applies to the sub-properties of addresses. You can order post-code before locality, or vice versa depending on cultural norms.
 +
 
 +
=== How do you convert a vCard to an hCard ===
 +
''Is there a way to convert a vCard to an hCard?''
 +
* There is no canonical conversion from a vCard to an hCard because you can construct an hCard in many different ways while expressing the same semantics. If you would like to recommend a suggested template hCard to use when displaying vCards in a browser, please propose it to the [http://microformats.org/discuss mailing list].
 +
 
 +
=== Are descendant elements recognized in a microformat ===
 +
''Are descendants recognized in a microformat property?''
 +
* Yes, for example:
 +
<source lang=html4strict>
 +
<span class="country-name">United States <small>of</small> America</span>
 +
</source>
 +
The output would be "United States of America".
 +
 
 +
=== Do properties like TEL use all descendants ===
 +
''Do properties like TEL use all descendants?'' e.g.
 +
<source lang=html4strict>
 +
<span class="tel">
 +
<span class="type">Home</span>:<span class="value">+1.234.567.8900</span>
 +
</span>
 +
</source>
 +
''Shouldn't that output be "TEL:Home: +1.234.567.8900"?''
 +
* No. class="value" is used to denote a sub-element which is used for the value of the property.  See [[hcard#Value_excerpting|Value excerpting]] for more details.
 +
 
 +
=== Can you have multiple value elements ===
 +
''Can you have multiple class="value" elements inside a property and what happens to them?''
 +
* Sure, for example:
 +
<source lang=html4strict>
 +
<span class="tel"><span class="type">Home</span>:<span class="value">+1</span>.<span class="value">234</span>.<span class="value">567</span>.<span class="value">8900</span></span>
 +
</source>
 +
would output: "+12345678900".
 +
 
 +
=== Can you mix properties and the root class name ===
 +
''<span id="nesting-properties">Can you put properties on the same element as the root class for a microformat? E.g. span class="vcard fn"?</span>''
 +
<!--
 +
;shortlink
 +
:http://tr.im/hcfnm
 +
-->
 +
* No, for several reasons:
 +
** It breaks the simple contextual CSS selector rule for finding and styling property values: .rootname .propertyname which will make it more difficult to write scoped CSS for the properties.  For more on why this is important see the [[faq#Class_interactions|microformats FAQ regarding class interactions]].
 +
** It will result in more confusion for parsers which may be parsing nested microformats.
 +
In this case in the question, you need two elements:
 +
* WRONG: <code>&lt;span class="vcard fn"></code>
 +
* RIGHT: <code>&lt;span class="vcard">&lt;span class="fn"></code>
 +
 
 +
The only time you can put a root class name (like "vcard") and a property class name on the same element, is when the root class name is basically providing an entire object as the value of the property which then belongs to some other object higher up the tree.
 +
 
 +
E.g. the [[hcalendar-brainstorming#hCard_locations|location of an hCalendar event also being an hCard]]:
 +
 
 +
<source lang=html4strict>
 +
<span class="vevent">
 +
  <span class="summary">HTML5 Developer Conference</span>,
 +
  <time class="dtstart">2013-04-01</time>...<time class="dtend">2013-04-03</time>, at
 +
  <span class="location vcard">
 +
    <span class="fn org">The Palace Hotel</span>,
 +
    <span class="adr"><span class="locality">San Francisco</span></span>
 +
  </span>
 +
</span>
 +
</source>
 +
 
 +
 
 +
Note the <code>&lt;span class="location vcard"></code> which specifies that the location of the outer [[hCalendar]] event is an entire [[hCard]] nested inside.
 +
 
 +
See also: [[faq#Can_you_mix_properties_and_the_root_class_name]]
 +
 
 +
=== Can you mix a property and its sub-properties ===
 +
''Can singular sub-properties be mixed with parents?''
 +
* No, all sub-properties MUST be on elements inside their parents.
 +
 
 +
=== Can you use query strings on email ===
 +
''What happened to the Query String on my email address?''
 +
* Query strings are removed from email addresses because they are not valid for importing to vCards
 +
 
 +
=== What types of email can you specify ===
 +
''What types of email can you specify? [[RFC2426]] Section 3.3.2 says "A non-standard value can also be specified." Does this refer to a non-standard e-mail address value or type value?''
 +
 
 +
* You can only specify the fixed set of "type" values documented by [[hcard#adr_tel_email_types|hCard: adr tel email types]], in this case, for the <code>email</code> property (case-insensitive)
 +
** <kbd>INTERNET</kbd>
 +
** <kbd>x400</kbd>
 +
** <kbd>pref</kbd>
 +
 
 +
=== Are ADR and TEL types case sensitive ===
 +
''Is the list of possible types for an ADR and TEL case sensitive?''
 +
* No, enumerated values are case-'''in'''sensitive, therefore Home, home, HOME, etc. are all equivalent.
 +
 
 +
=== How does GEO work with ABBR ===
 +
''What happens to the GEO sub-properties when GEO is used with ABBR?''
 +
* The GEO property can be represented two different ways:
 +
<source lang=html4strict>
 +
<span class="geo">
 +
<span class="latitude">123.45</span>
 +
<span class="longitude">67.89</span>
 +
</span>
 +
 
 +
<abbr class="geo" title="123.45;67.89">My House</abbr>
 +
</source>
 +
 
 +
When used with an <code>&lt;abbr&gt;</code> element the latitude and longitude are separated by a semicolon.
 +
 
 +
=== How do you mark up a phone extension ===
 +
''How do I mark up a phone extension in hCard?''
 +
There doesn't seem to be a way to declare a telephone extension in the vCard RFC 2426 spec, the suggested way is currently:
 +
<source lang=html4strict>
 +
<span class="tel">
 +
    <span class="type">work</span>: <span class="value">800 555-1212 x 1234</span>
 +
</span>
 +
</source>
 +
 
 +
RFC 3966 suggests that an extension be indicated with ";ext=" for example:
 +
<source lang=html4strict>
 +
<span class="tel">
 +
    <span class="type">work</span>: <span class="value">800 555-1212;ext=1234</span>
 +
</span>
 +
</source>
 +
although that is more relevant when used as a URI:
 +
<source lang=html4strict>
 +
<span class="tel">
 +
    <span class="type">work</span>: <a class="value" href="tel:+18005551212;ext=1234">800 555-1212;ext=1234</a>
 +
</span>
 +
</source>
 +
 
 +
[http://groups.google.com/group/comp.std.internat/msg/24fc32228689a620?dmode=source ITU-T Recommendation E.123 1.6] specifies the use of the word "extension" or abbreviation thereof:
 +
 
 +
    Telephone International +22 607 123 4567 ext. 876
 +
 
 +
The above example may be better as:
 +
 
 +
<source lang=html4strict>
 +
<span class="tel">
 +
    <span class="type">work</span>: <a class="value" href="tel:+18005551212;ext=1234">800 555-1212 ext. 1234</a>
 +
</span>
 +
</source>
 +
 
 +
=== How do you encode IM accounts ===
 +
''How do I encode my IM account in hCard?''
 +
* see [[hcard-examples#New_Types_of_Contact_Info|hCard examples: New Types of Contact Info]]
 +
 
 +
=== Can you hCard the deceased ===
 +
''How do you make an hCard for the deceased?''
 +
* As you normally would, and add the tag "deceased".
 +
* vCards and thus hCard does not have a date-of-death property. You may wish to explore the biographical or [[genealogy-formats]] microformats efforts.
 +
* See also [[vcard-suggestions#Deceased]]
 +
 
 +
=== Any plans for xparams ===
 +
''Are there plans to include x-parameters in future versions of hCard?''
 +
* No. The problem is that each of these x-parameters are vendor specific and are not part of the RFC. Secondly, there is no way to be 100% sure that 'x-foobar' is not just a content-specific HTML class name that the publisher is using for CSS styling.
 +
 
 +
=== What is a word in implied optimizations ===
 +
''What constitutes a "word" for the purpose of 'implied-n optimization'?''
 +
* "N" can be implied from "FN" when the content of "FN" is broken into two "words" separated by whitespace. For this purpose, a "word" is any sequence of non-whitespace characters including but not limited to low- and high-range alphanumerics and punctuation. A "word" can be characterised by the following regular expression: <source lang=text>/\S+/</source>
 +
 
 +
=== How do you create non English title attributes===
 +
''My website is not in English and I want the title attributes (sown as "tooltips", in many browsers) to be in my native language''
 +
* Properties such as class="type" require an enumerated list of English words. It is possible to use your native language for the displayed title, but still use the English work for the class="type" without it being shown.
 +
<source lang=html4strict>
 +
<abbr class="type" title="home">
 +
<span title="[your native word for home here]">
 +
  to my home
 +
</span>
 +
</abbr>
 +
</source>
 +
 
 +
Having an span with a title attribute inside the abbr element will only display the title on the span, where you have the text (your native word for home here).
 +
 
 +
=== How do you add categories to an hCard ===
 +
''How do you add categories to an hCard?''
 +
* The short answer is, you {{must}} use class="category" and {{should}} also use [[rel-tag|rel="tag"]], e.g. if you wanted to tag someone with the category "microformats", you would put this in their hCard:
 +
<source lang=html4strict>
 +
<a class="category" rel="tag"
 +
  href="http://en.wikipedia.org/wiki/microformats">microformats</a>
 +
</source>
 +
 
 +
=== How are category and rel-tag related ===
 +
''What is the relationship between the CATEGORY property and [[rel-tag]]?''
 +
* Categories can optionally be represented as tags. The classname 'category' {{must}} always be used, but rel="tag" can optionally be used (in addition). In the case that a rel-tag tag is used, the tag (as defined by [[rel-tag]]) is used for the category. Examples:
 +
 
 +
<source lang=html4strict>
 +
<span class="category">food</span>
 +
</source>
 +
 
 +
<source lang=html4strict>
 +
<a class="category" rel="tag" href="http://example.com/food">Food</a>
 +
</source>
 +
 
 +
=== Why not put type for tel or adr into class ===
 +
''Why not put the 'type' value for the 'tel' or 'adr' properties into the class name? E.g. <code><nowiki><span class="fax">(415) 555-1212</span></nowiki></code>''
 +
* This was actually initially attempted and [[hcard-parsing#ISSUE_2|rejected]] because it constituted storage of content in the class attribute, which is an anti-design-pattern.  The "type" in this case is essentially a "tag" on the phone number, which is human readable content, and thus should be visible, rather than hidden in an invisible class attribute.  In addition, polluting the class attribute with content text makes it significantly harder to use it for the intended use, which is to add/refine semantics of existing element names.
 +
 
 +
=== How do I markup multiple addresses ===
 +
''How do I markup separate addresses, like for home and work?''
 +
* You need two elements with class name "adr" and the appropriate sub-properties. E.g. derived from [[hcard-examples#3.2.1_ADR_Type_Definition|hCard examples]]:
 +
<source lang=html4strict>
 +
<div class="adr">
 +
<span class="type">home</span> address:
 +
<div class="street-address">123 Main Street</div>
 +
<span class="locality">Any Town</span>, <span class="region">CA</span>,
 +
<span class="postal-code">91921-1234</span>
 +
</div>
 +
<div class="adr">
 +
<span class="type">work</span> address:
 +
<div class="street-address">789 Main Street</div>
 +
<span class="locality">Any Town</span>, <span class="region">CA</span>,
 +
<span class="postal-code">91921-1234</span>
 +
</div>
 +
</source>
 +
As a result, note that each element with class name "adr" is treated as a separate address with its own subproperties and values.
 +
 
 +
=== Why is IMG alt not being picked up ===
 +
''I have my name in an <code><nowiki><img></nowiki></code> alt attribute and it is not being picked up by hCard tools. Why not?''
 +
 
 +
You can use an <code><nowiki><img></nowiki></code> alt value to specify any text (i.e. not URL) property value by placing the class name <em>directly</em> on the <code><nowiki><img></nowiki></code> element itself. Other element alternatives are documented in [[hcard#Human_vs._Machine_readable|hCard: Human vs. Machine readable]]. 
 +
 
 +
Here is an example of doing it WRONG and the corrected RIGHT way.  White space added for readability:
 +
 
 +
<h4>WRONG</h4>
 +
 
 +
<pre style="background:#FEE"><nowiki>
 +
<span class="vcard">
 +
<a class="url fn photo" href="http://tantek.com">
 +
  <img src="http://tantek.com/icon80.jpg" alt="Tantek Çelik" />
 +
</a>
 +
</span>
 +
</nowiki></pre>
 +
 
 +
<h4>RIGHT</h4>
 +
Note the moving of the class names "fn" and "photo" from the <nowiki><a></nowiki> to the <nowiki><img></nowiki>
 +
 
 +
<pre style="background:#EFE"><nowiki>
 +
<span class="vcard">
 +
<a class="url" href="http://tantek.com">
 +
  <img class="fn photo" src="http://tantek.com/icon80.jpg" alt="Tantek Çelik" />
 +
</a>
 +
</span>
 +
</nowiki></pre>
 +
 
 +
Some have suggested having the IMG alt (and other such textual alternatives) <em>always</em> be part of surrounding property values, and while this may initially seem appealing, this was deliberately rejected at the creation of hCard to give publishers more control.
 +
 
 +
In addition all too often there is "garbage" (or just extra unwanted text) in alt attributes for a variety of publisher reasons, and that extraneous text would pollute otherwise clean property values in numerous existing sites.
 +
 
 +
Thus only if the publisher explicitly <em>wants</em> the text from the alt attribute do they add the respective class value to get it.
 +
 
 +
Finally, it is <em>simpler</em> and more predictable for publishers if they know that for images and other such URL related elements (a, object, etc.) that whether they are specifying a URL property (like "email", "photo", "url", etc.) or a text property (like "fn", "nickname", etc.) in either case <em>directly</em> specifying the property on the element is the way to do it.
 +
 
 +
=== How do I mark up each ADR with a GEO ===
 +
''I have an hCard with multiple addresses. How do I mark-up each ADR with a GEO?''
 +
 
 +
* Short answer: don't.  See also [[hcard-faq#Can_a_GEO_be_inferred_from_an_ADR_in_an_hCard|Can a GEO be inferred from an ADR in an hCard]].
 +
* Longer: There are two reasons not to mark-up an ADR with a GEO. 
 +
** First and most importantly, ADR and GEO don't mean the same thing, therefore you MUST NOT simply mark-up an ADR with a GEO.
 +
** Second, even if you did consider them to be the same information, you shouldn't do so for DRY (Don't Repeat Yourself) reasons.  Duplicating information increases the probability inconsistent information due to one copy being updated without the other being updated.
 +
* Details: ADR and GEO represent different semantics, an ADR representing <em>an</em> address of the hCard object (thus hCards may have multiple ADRs), whereas a GEO if present represents <em>the</em> physical location of the hCard object (thus an hCard may have at most a single GEO). In addition, they represent a different data <em>types</em>, i.e. an ADR represents an area of land which is a polygon (or perhaps a space in a building which is a polyhedron), whereas a GEO only represents a single point.<p>Attempting to duplicate an ADR with a GEO property with nearby/representative coordinates (e.g. as you might derive  by using an online mapping service) is also undesirable from the DRY perspective for all the usual duplicates getting out of sync problems.</p>
 +
 
 +
=== How do I markup an unstructured location ===
 +
''If I have a location field which is unstructured, how do I mark that up?  I might have a user typing "San Francisco" or "San Francisco, CA" or "USA", etc.''
 +
 
 +
* use the "label" property. E.g.
 +
<source lang=html4strict>
 +
<span class="label">San Francisco, CA</span>
 +
</source>
 +
 
 +
=== Partial Dates ''or'' A Gentleman Never Asks ===
 +
* ''I want to mark up someone's date of birth, but don't know which year they were born in.''
 +
* ''I want to mark up someone's date of birth, but only know which year they were born in.''
 +
 
 +
The [[date-design-pattern|date design pattern]] recommends using ISO 8601 dates, compatible with W3CDTF or RFC 3339 (which are both subsets of ISO 8601). Fortunately W3CDTF allows for partial dates. For example:
 +
 
 +
* <code>&lt;abbr class="bday" title="2008-09">Sept 2008&lt;/abbr></code>
 +
* <code>&lt;abbr class="bday" title="2008">2008&lt;/abbr></code>
 +
 
 +
Such dates are supported by ''most'' microformat parsers. ISO 8601 also allows for dates to be provided without the year (and even without the month):
 +
 
 +
* <code>&lt;abbr class="bday" title="--09-01">1 Sept&lt;/abbr></code>
 +
* <code>&lt;abbr class="bday" title="---01">the first of the month&lt;/abbr></code>
 +
 
 +
These dates are not compatible with W3CDTF or RFC 3339, and have less broad-ranging support in microformat parsers. It should also be noted that the vCard specification requires dates to include years, so even if your microformat parser supports one of these formats, it would probably have to fill in a dummy year when providing a vCard output.
 +
 
 +
=== What is AGENT ===
 +
''What is the "agent" property for in hCard?''
 +
 
 +
From Ben Ward on IRC
 +
 
 +
In business context, the main vcard could be, for example ‘Dana B. Lawyer’, and her vcard contains an AGENT for ‘Joe Secretary’.  It is someone who acts as an ‘agent’ of the main person.
 +
 
 +
=== Can hCards use variants of properties like Given-Name or country ===
 +
''Can hCards use variants of properties like "Given-Name" or "country"?''
 +
 
 +
No. Only the precise lowercase property names in the hCard spec are valid (see related: [[faq#Q._Are_class_names_case_sensitive.3F|case-sensitive]]).
 +
 
 +
The following variations that folks have asked about are all invalid and {{must}} be ignored in hCards:
 +
 
 +
* <code>Given-Name</code> - microformats properties are all lowercase, use <code>given-name</code>
 +
* <code>Family-Name</code> - ""
 +
* <code>Street-Address</code> - ""
 +
* <code>country</code> - use <code>country-name</code>
 +
 
 +
Each of these could perhaps form the basis of a simple hCard parsing error test.  See also:
 +
* [[hcard-parsing]]
 +
* [[hcard-examples]]
 +
 
 +
 
 +
<h2> Related Pages </h2>
 +
{{hcard-related-pages}}

Current revision


This documents frequently asked questions and answers (FAQs) about hCard. For FAQs regarding microformats in general, or across microformats, see the microformats FAQ.

If you have a new question to ask, please consider first asking your question on the microformats irc channel (preferably) or the microformats-discuss mailing list. New questions and answers should be added to the end of the list. If you have a new question but not an answer, please add it to hCard issues.

Contents

Editing this Page

Please do not use "?" or other punctuation in the headers - it helps to keep the URLs to their fragment identifiers shorter and easier to read, copy/paste etc. See how-to-play for more wiki editing guidelines.

Q&A

What is the point of hCard

What is the point of hCard to people, businesses, etc.?

How is hCard different than just links

How is hCard different than just links?

How does hCard help users

How does hCard help users, e.g. how does it improve the user experience in browsers more than just providing name and email as text?

How can I style hCards with CSS

How can I style hCard with CSS?

How do I convert hCards to vCards for download on a site

Is there any live way to convert hCards to vCards for download on a site? In other words, I have added hCard to my page, but i'd like my users to have a 'download vCard' button.

<a href="http://h2vx.com/vcf/YOURURLHERE">download vCard</a>

Consider using more user-friendly text as well, like Add to Address Book. There are many examples of this in the hCard Examples in the Wild page. Note that the H2VX hCard to vCard service is based on the open source XSLT "X2V" by Brian Suda and others. If you want, you can install X2V yourself and run your own local converter.

Should I use ADDRESS for hCards

Should I use the more semantic <address> element for my hCards?

For more on different types of significant hCards for pages, and semantics distinctions among them, see hcards-and-pages.

Why is adr property necessary

What is the point of class="adr" when we have the <address> element?.- 2006-12-04 asked by Joshie Surber.

Why is url property necessary

Why is it necessary to put class name "url" on URL elements in the hCard when those hyperlinks already start with "http://", and that is enough to distinguish them from email links?

Can an hCard have multiple URLs

Can an hCard have multiple URLs?

I have a problem with serving a vCard vcf file

I have a problem with serving a vCard .vcf file that has the info from my /contact/ page from my website. E.g. browsers just display the text of the vCard .vcf file instead of downloading it.

The easiest thing to do and support (especially with more and more vCard consumers out there with their own quirks) is to:

  1. Add hCard markup to your /contact/ page where you already have your contact info visible in the content. See also the hCard creator which is a useful tool for learning how hCard markup works.
  2. Change the link to your vCard .vcf file to point to: http://h2vx.com/vcf/http://yourwebsite.example.com/contact/

This way you won't have to worry about duplicate data either - just update the content on your contact page marked up in hCard and anyone that gets your vCard will automatically get your updated info without you having to worry about updating separate file.

How do I support an existing vCard URL

I already have a vCard that I keep up-to-date. I don't want to change any references to it because it might break something else, what can I do?

RewriteRule ^path/to/old.vcf http://h2vx.com/vcf/http://example.com/hCard_encoded.htm&filename=old.vcf

Now you shouldn't have to do anything else, all links to the "old.vcf" are redirected to the webservice and will return a new vCard that is dynamially generated from your page.

I think that using 'Redirect' is better than using mod_rewrite (is not enabled on some hosts) --Robert Bachmann

Redirect /path/to/old.vcf http://h2vx.com/vcf/http://example.com/hCard_encoded.htm&filename=old.vcf

Why does my hCard photo not show up in Address Book

Why are photos not working for me when I import my hCard as a vCard into the Apple Address Book?

Why does hCard use vcard as the root class name

hCard maps the properties and values of the vCard standard (RFC2426), hence the use of the vcard class name inside the HTML markup. More background on the reasons behind that decision here: hCard Parsing: Root Class Name.

What are plural hCard properties

Is there a list of all hCard properties which can be plural?
Is there a list of all the properties which can have multiple instances?

How do you mark up an organization

How do I create an hCard for an organization or a company?

Mark up hCards for organizations or companies by using both the "fn" and "org" properties for the name of the organization/company. E.g.

<p class="vcard">You can help support
 <span class="fn org">microformats.org</span>
 by publishing microformats on your web pages, 
 adding microformats support to your tools, 
 giving constructive feedback on the wiki, 
 and participating in discussions on IRC channel
</p>

See also: hCard authoring: Organization hCards.

What does FN stand for

What does FN stand for?

Type purpose: To specify the formatted text corresponding to the name of the object the vCard represents.

How do you mark up a first or last name

I don't see anything for first/last names.

See hCard authoring: Importance of Names for examples.

How do you mark up a middle name or initial

How does one handle middle initials/names in hCard?

How do you mark up suffixes

How does one handle suffixes, both family related and honorific?

<abbr class="honorific-suffix" title="Junior">Jr.</abbr>

How do you mark up city state and zip

How do you mark up the city, state, and zip code of an address?

How is gender represented

How do you represent gender in hCard?

If you're using microformats2:

If you're using hCard:

It is possible to represent gender implicitly in the honorific-prefix field, e.g. Mr. for male, and Ms. for female:

<span class="honorific-prefix">Mr.</span>

or

<span class="honorific-prefix">Ms.</span>

This approach does have the limitation that "Mr." and "Ms." (or "Miss"/ "Mrs.") may conflict with a higher-ranking, gender-neutral honorific, such as "Dr." or "Rev." for the person, as it is unusual to refer to someone as "Mr. Dr." or "Mrs. Rev." for example. See hcard-issues.

See also the gender research page.

Can a hCard contain extra elements

Is it OK for an hCard node to contain extra elements?

Can a GEO be inferred from an ADR in an hCard

Can I automatically add GEO from an address when transforming an hCard to vCard if it is not present?

X2V does not convert email with name as plain text

X2V doesn't convert my email address correctly, it is in the form href="FirstName LastName <Email@example.com>"

One possible valid hCard markup would be:

<span class="vcard">
  <span class="fn">Firstname Lastname</span>
 &amp;lt;<a class="email" href="mailto:Email@example.com">Email@example.com</a>&amp;gt;
</span>

This might be displayed as:

Firstname Lastname <email@example.com>

What hCard properties are required

What properties are required in an hCard?

Does N property require all sub-properties

If I use the 'n' property, do I have to use ALL of the sub-properties?

Do FN and N need to be on same element

Do the 'fn' and 'n' properties have to be on the same element?

<p class="vcard">My name is
<span class="n">
<span class="honorific-prefix">Mr.</span>
<span class="given-name">John</span>
<span class="additional-name">Q</span>
<span class="family-name">Public</span>
</span>
but you can just call me
<span class="fn">Johnny</span>
</p>

Can FN be in a backwards order and N still extract the information correctly

Can FN be in a backwards order and N still extract the information correctly?

<span class="fn n"><span class="family-name">Smith</span>,  <span
class="given-name">John</span></span>

The FN value would be "Smith, John", but the N value would correctly extract "John" as the given name, and "Smith" as the family name. This is useful for some cultures which reverse the name order.

The same applies to the sub-properties of addresses. You can order post-code before locality, or vice versa depending on cultural norms.

How do you convert a vCard to an hCard

Is there a way to convert a vCard to an hCard?

Are descendant elements recognized in a microformat

Are descendants recognized in a microformat property?

<span class="country-name">United States <small>of</small> America</span>

The output would be "United States of America".

Do properties like TEL use all descendants

Do properties like TEL use all descendants? e.g.

<span class="tel">
 <span class="type">Home</span>:<span class="value">+1.234.567.8900</span>
</span>

Shouldn't that output be "TEL:Home: +1.234.567.8900"?

Can you have multiple value elements

Can you have multiple class="value" elements inside a property and what happens to them?

<span class="tel"><span class="type">Home</span>:<span class="value">+1</span>.<span class="value">234</span>.<span class="value">567</span>.<span class="value">8900</span></span>

would output: "+12345678900".

Can you mix properties and the root class name

Can you put properties on the same element as the root class for a microformat? E.g. span class="vcard fn"?

In this case in the question, you need two elements:

The only time you can put a root class name (like "vcard") and a property class name on the same element, is when the root class name is basically providing an entire object as the value of the property which then belongs to some other object higher up the tree.

E.g. the location of an hCalendar event also being an hCard:

<span class="vevent">
  <span class="summary">HTML5 Developer Conference</span>, 
  <time class="dtstart">2013-04-01</time>...<time class="dtend">2013-04-03</time>, at
  <span class="location vcard">
    <span class="fn org">The Palace Hotel</span>, 
    <span class="adr"><span class="locality">San Francisco</span></span>
  </span>
</span>


Note the <span class="location vcard"> which specifies that the location of the outer hCalendar event is an entire hCard nested inside.

See also: faq#Can_you_mix_properties_and_the_root_class_name

Can you mix a property and its sub-properties

Can singular sub-properties be mixed with parents?

Can you use query strings on email

What happened to the Query String on my email address?

What types of email can you specify

What types of email can you specify? RFC2426 Section 3.3.2 says "A non-standard value can also be specified." Does this refer to a non-standard e-mail address value or type value?

Are ADR and TEL types case sensitive

Is the list of possible types for an ADR and TEL case sensitive?

How does GEO work with ABBR

What happens to the GEO sub-properties when GEO is used with ABBR?

<span class="geo">
<span class="latitude">123.45</span>
<span class="longitude">67.89</span>
</span>
 
<abbr class="geo" title="123.45;67.89">My House</abbr>

When used with an <abbr> element the latitude and longitude are separated by a semicolon.

How do you mark up a phone extension

How do I mark up a phone extension in hCard? There doesn't seem to be a way to declare a telephone extension in the vCard RFC 2426 spec, the suggested way is currently:

<span class="tel">
    <span class="type">work</span>: <span class="value">800 555-1212 x 1234</span>
</span>

RFC 3966 suggests that an extension be indicated with ";ext=" for example:

<span class="tel">
    <span class="type">work</span>: <span class="value">800 555-1212;ext=1234</span>
</span>

although that is more relevant when used as a URI:

<span class="tel">
    <span class="type">work</span>: <a class="value" href="tel:+18005551212;ext=1234">800 555-1212;ext=1234</a>
</span>

ITU-T Recommendation E.123 1.6 specifies the use of the word "extension" or abbreviation thereof:

   Telephone International +22 607 123 4567 ext. 876

The above example may be better as:

<span class="tel">
    <span class="type">work</span>: <a class="value" href="tel:+18005551212;ext=1234">800 555-1212 ext. 1234</a>
</span>

How do you encode IM accounts

How do I encode my IM account in hCard?

Can you hCard the deceased

How do you make an hCard for the deceased?

Any plans for xparams

Are there plans to include x-parameters in future versions of hCard?

What is a word in implied optimizations

What constitutes a "word" for the purpose of 'implied-n optimization'?

How do you create non English title attributes

My website is not in English and I want the title attributes (sown as "tooltips", in many browsers) to be in my native language

<abbr class="type" title="home">
 <span title="[your native word for home here]">
  to my home
 </span>
</abbr>

Having an span with a title attribute inside the abbr element will only display the title on the span, where you have the text (your native word for home here).

How do you add categories to an hCard

How do you add categories to an hCard?

<a class="category" rel="tag" 
   href="http://en.wikipedia.org/wiki/microformats">microformats</a>

How are category and rel-tag related

What is the relationship between the CATEGORY property and rel-tag?

<span class="category">food</span>
<a class="category" rel="tag" href="http://example.com/food">Food</a>

Why not put type for tel or adr into class

Why not put the 'type' value for the 'tel' or 'adr' properties into the class name? E.g. <span class="fax">(415) 555-1212</span>

How do I markup multiple addresses

How do I markup separate addresses, like for home and work?

<div class="adr">
 <span class="type">home</span> address:
 <div class="street-address">123 Main Street</div>
 <span class="locality">Any Town</span>, <span class="region">CA</span>, 
 <span class="postal-code">91921-1234</span>
</div>
<div class="adr">
 <span class="type">work</span> address:
 <div class="street-address">789 Main Street</div>
 <span class="locality">Any Town</span>, <span class="region">CA</span>, 
 <span class="postal-code">91921-1234</span>
</div>

As a result, note that each element with class name "adr" is treated as a separate address with its own subproperties and values.

Why is IMG alt not being picked up

I have my name in an <img> alt attribute and it is not being picked up by hCard tools. Why not?

You can use an <img> alt value to specify any text (i.e. not URL) property value by placing the class name directly on the <img> element itself. Other element alternatives are documented in hCard: Human vs. Machine readable.

Here is an example of doing it WRONG and the corrected RIGHT way. White space added for readability:

WRONG

<span class="vcard">
 <a class="url fn photo" href="http://tantek.com">
  <img src="http://tantek.com/icon80.jpg" alt="Tantek Çelik" />
 </a>
</span>

RIGHT

Note the moving of the class names "fn" and "photo" from the <a> to the <img>

<span class="vcard">
 <a class="url" href="http://tantek.com">
  <img class="fn photo" src="http://tantek.com/icon80.jpg" alt="Tantek Çelik" />
 </a>
</span>

Some have suggested having the IMG alt (and other such textual alternatives) always be part of surrounding property values, and while this may initially seem appealing, this was deliberately rejected at the creation of hCard to give publishers more control.

In addition all too often there is "garbage" (or just extra unwanted text) in alt attributes for a variety of publisher reasons, and that extraneous text would pollute otherwise clean property values in numerous existing sites.

Thus only if the publisher explicitly wants the text from the alt attribute do they add the respective class value to get it.

Finally, it is simpler and more predictable for publishers if they know that for images and other such URL related elements (a, object, etc.) that whether they are specifying a URL property (like "email", "photo", "url", etc.) or a text property (like "fn", "nickname", etc.) in either case directly specifying the property on the element is the way to do it.

How do I mark up each ADR with a GEO

I have an hCard with multiple addresses. How do I mark-up each ADR with a GEO?

How do I markup an unstructured location

If I have a location field which is unstructured, how do I mark that up? I might have a user typing "San Francisco" or "San Francisco, CA" or "USA", etc.

<span class="label">San Francisco, CA</span>

Partial Dates or A Gentleman Never Asks

The date design pattern recommends using ISO 8601 dates, compatible with W3CDTF or RFC 3339 (which are both subsets of ISO 8601). Fortunately W3CDTF allows for partial dates. For example:

Such dates are supported by most microformat parsers. ISO 8601 also allows for dates to be provided without the year (and even without the month):

These dates are not compatible with W3CDTF or RFC 3339, and have less broad-ranging support in microformat parsers. It should also be noted that the vCard specification requires dates to include years, so even if your microformat parser supports one of these formats, it would probably have to fill in a dummy year when providing a vCard output.

What is AGENT

What is the "agent" property for in hCard?

From Ben Ward on IRC

In business context, the main vcard could be, for example ‘Dana B. Lawyer’, and her vcard contains an AGENT for ‘Joe Secretary’. It is someone who acts as an ‘agent’ of the main person.

Can hCards use variants of properties like Given-Name or country

Can hCards use variants of properties like "Given-Name" or "country"?

No. Only the precise lowercase property names in the hCard spec are valid (see related: case-sensitive).

The following variations that folks have asked about are all invalid and MUST be ignored in hCards:

Each of these could perhaps form the basis of a simple hCard parsing error test. See also:


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 FAQ was last modified: Sunday, March 15th, 2015

Views