hcard-faq: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
(more clarification on proper (and improper) uses of <address>)
(Added 11-21 FAQs)
Line 53: Line 53:
<li>''What properties are required in hcard?''
<li>''What properties are required in hcard?''
* The only required property is n (the structured name), but that can under certain circumstances, be inferred from the <code>fn</code> property.
* The only required property is n (the structured name), but that can under certain circumstances, be inferred from the <code>fn</code> property.
<li>''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
<li>''Does the 'FN' and 'N' properties have to be on the same element?''
* No, you can have the FN and the N be on two seperate elements, for example:
<pre><nowiki>
<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">Johnney</span>
</p>
</nowiki></pre>
<li>''Is there a way to convert a vCard to an hCard?''
* Currently, no. There are no plans at this time to do so. The issue is that once you convert to HTML, how do you represent it? Since microfomats can be on any valid HTML element which do you use? how do you represent dates? etc. The is out of the scope of microformats
<li>''Are ancestors recognized in a microformat property?''
* Yes, for example:
<pre><nowiki>
<span class="country-name">United States <small>of</small> America</span>
</nowiki></pre>
The output would be "United States of America" all ancestors are used.
<li>''But what about properties like TEL?''
* <pre><nowiki>
<span class="tel"><span class="type">Home</span>:<span class="value">+1.234.567.8900</span></span>
</nowiki></pre>
Shouldn't that output be "TEL:Home: +1.234.567.8900"?
No, because of the class="value" is present, ONLY the values contained within that property are used.
<li>''Can you have multiple class="values"s and what happens to them?''
* Sure, this example would output: "+12345678900"
<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>
</nowiki></pre>
<li>''Can you take a short-cut and make class="vcard fn"?''
* No, from a data format design perspective, breaking strict containment will result in other problems!
<li>''Can singular sub-properties be mixed with parents?''
* No, all sub-properties MUST be on elements inside their parents.
<li>''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
<li> ''Is the list of possible types for an ADR and TEL case sensitive?''
* No, enumerated values are case-INsensitive, therefore Home, home, HOME, etc are all equivalent
<li>''What happens to the GEO sub-properties when GEO is used with ABBR?''
* The GEO property can be represented two different ways:
<pre>
<nowiki>
<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>
</nowiki>
</pre>
When used with an &lt;abbr&gt; element the latitude and longitude are seperated by a semicolon.
</ol>
</ol>

Revision as of 00:48, 11 May 2006

hCard FAQ

This page is for documenting Q&A about hCard. If you have a new question to ask, Please consider first asking your question on the microformats-discuss list.

Q&A

  1. Should I use the more semantic <address> element for my hCards?
    • 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 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 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>.
      In short, DO NOT use <address> to markup addresses in general. Only use it to markup the contact information for the page (or major part thereof), and when doing so, use it to markup the entire contact information (via <address class="vcard">), not just the address of the contact.
  2. 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.
  3. 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
RewriteRule ^path/to/old.vcf http://suda.co.uk/projects/X2V/get-vcard.php\?uri=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://suda.co.uk/projects/X2V/get-vcard.php?uri=http://example.com/hCard_encoded.htm&filename=old.vcf
  1. Is there a list of all hCard properties which can be plural?
    • 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).
      1. Check the hCard XMDP profile for the property definition.
      2. 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.
      3. Else go check the referenced section in RFC 2426 which should state explicitly whether or not the property is plural or singular.
      4. Else (if RFC 2426 is *not* explicit) then the property is plural.
  1. What does FN stand for?
    • FN stands for "Formatted Name." From Section 3.1.1 of the RFC:

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

    • 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.
  2. How do you represent gender in hCard?
    • There is no GENDER property in vCard RFC2426. 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:
    <span class="honorific-prefix">Mr.</span>
    

    or

    <span class="honorific-prefix">Ms.</span>
    
  3. Is it OK for an hCard node to contain extra elements?
    • Yes, parsers will ignore anything they don't understand.
  4. Can I automatically add GEO from an address when transfoming 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
  5. X2V doesn't convert my email address correctly, it is in the form href="FirstName LastName <Email@Address.com>"
    • While that form of email address works for some programs such as outlook, it is not a valid mailto: value (see RFC2368) the FirstName and LastName should be omitted.
  6. What properties are required in hcard?
    • The only required property is n (the structured name), but that can under certain circumstances, be inferred from the fn property.
  7. 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
  8. Does the 'FN' and 'N' properties have to be on the same element?
    • No, you can have the FN and the N be on two seperate elements, for example:
    <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">Johnney</span>
    </p>
    
  9. Is there a way to convert a vCard to an hCard?
    • Currently, no. There are no plans at this time to do so. The issue is that once you convert to HTML, how do you represent it? Since microfomats can be on any valid HTML element which do you use? how do you represent dates? etc. The is out of the scope of microformats
  10. Are ancestors recognized in a microformat property?
    • Yes, for example:
    <span class="country-name">United States <small>of</small> America</span>
    

    The output would be "United States of America" all ancestors are used.

  11. But what about properties like TEL?
    <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"?

    No, because of the class="value" is present, ONLY the values contained within that property are used.

  12. Can you have multiple class="values"s and what happens to them?
    • Sure, this example would output: "+12345678900"
    Home:+1.+234.567.8900 </nowiki>
  13. Can you take a short-cut and make class="vcard fn"?
    • No, from a data format design perspective, breaking strict containment will result in other problems!
  14. Can singular sub-properties be mixed with parents?
    • No, all sub-properties MUST be on elements inside their parents.
  15. 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
  16. Is the list of possible types for an ADR and TEL case sensitive?
    • No, enumerated values are case-INsensitive, therefore Home, home, HOME, etc are all equivalent
  17. What happens to the GEO sub-properties when GEO is used with ABBR?
    • The GEO property can be represented two different ways:
    
    <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 seperated by a semicolon.