Difference between revisions of "microformats2-faq"

From Microformats Wiki
Jump to navigation Jump to search
(How do you use experimental microformats and property names)
(→‎see also: adding experimental properties link)
Line 124: Line 124:
* [[microformats2]]
* [[microformats2]]
* [[microformats2-brainstorming]]
* [[microformats2-brainstorming]]
* [[microformats2-experimental-properties]]
* [[microformats2-prefixes]]
* [[microformats2-prefixes]]
* [[microformats2-faq]]
* [[microformats2-faq]]

Revision as of 14:50, 11 July 2015

<entry-title>microformats2 FAQ</entry-title>

Frequently asked questions about microformats2.

when using both h-card and vcard which should be first and why

Q: When using both microformats2 and traditional microformats for backwards compatibility, which class name should go first and why? Another example: should "h-event" be first (before the "vevent") in the class attribute?

A: Use the microformats2 class names first, and in equivalent pairs when marking up more than one property. E.g.

<span class="h-card vcard">
  <a class="p-name fn p-org org u-url url" 

<span class="h-event vevent">
  <a class="p-name summary u-url url"
     href="http://plancast.com/p/e83d">microformats meetup SF</a>, 
  <time class="dt-start dtstart">2012-11-14 18:00</time>

Here's how:

And why:

  • The prefixes (h-, p-, etc.) of microformats2 class names provide easier recognition (as class names for microformats), and when followed by the similarly named existing class name, they're more easily recognized as related and thus kept together when the markup is moved or maintained over time.

why are microformats 2 properties prefixed

Q: Why do microformats 2 property class names have prefixes like 'p-', 'u-', 'dt-', 'e-' ?

A: For the benefit of both web authors and developers of parsers/consumers. By using class names with a small handful of short easily recognizable prefixes, it's easier to see which class names belong to microformats, and which may serve other purposes on the page. This helps web designers better recognize and maintain support for microformats across site redesigns for example. In particular:

  • The 'p-' prefix is for typical string properties and parsing thereof.
  • 'u-' is for URL-like properties whose values often come from another attribute such as the <a> 'href' or <img> 'src'.
  • 'dt-' is for date and time related properties that have a particular format themselves, and ideally should make good use of the HTML5 <time> element, though for backward compatibility they work on any element.
  • Finally, 'e-' is for properties whose value is the entirety of the text and HTML inside an element, as represented by the element's DOM. The 'e-entry-content' property from hAtom for example permits marking up and parsing/extracting an entire post from an HTML blog post page to an Atom feed entry with full markup/DOM fidelity of the original post.

Since prefixes determine specific parsing rules, parser developers are able to write simple and efficient generic microformats 2.0 parsers without needing to know any specific vocabularies, either currently or in the future. These are both advantages of microformats 2.0 over original microformats. For more details, including why and how microformats 2.0 class name prefixes were developed, see: microformats2 prefix conventions.

how do you use experimental microformats and property names

I.e. what is the correct way to start using experimental microformats and property names in microformats2?

Documented primarily as microformats2 vendor extensions, here's a quick summary:

There are two cases:

1. Vendor-specific - extensions that either only make sense in or have a very specific detailed or other meaning (e.g. a shibboleth) in a particular company or organizational context.

Use -vendorabbr- immediately after a microformats2 prefix, where "vendorabbr" is an abbreviation for the company (e.g. stock symbol) or organiztion. E.g.

  • h-goog-volcano for a proprietary "volcano" object
  • p-osm-shop for an OSM-site specific "shop" property

2. Experimental - ideas that authors/developers want to experiment with in the wild without going through the microformats The microformats process to craft well-researched microformats and property names. Or for experimental formats that you're not even sure would be worth trying to standardize, may apply to a narrow / small community etc. (which might still grow as a result of experimentation, and thus eventually merit a format).

Use -x- immediately after a microformats2 prefix, e.g.:

  • h-x-test-fixture for an experimental "text-fixture" format (e.g. for a microformats test suites).
  • p-x-prep-time - a possible experimental preparation time property to be added to hRecipe 0.22 upon consideration/documentation of real-world usage/uptake.

how do h-adr and h-geo work with an implied name property

Q: Some microformats like h-adr and h-geo are usually used as just collections of properties and typically lack explicit names or "p-name" properties. How does the implied "name" property work with such microformats?

A: First, there is the use-case of named locations which aren't necessarily full h-card venues in and of themselves. For named locations, the name is published in visible text and should be marked up with e.g. class="p-name".

Other h-adr and h-geo microformats which lack an explicit name will have a name implied for them (e.g. from the full text of the element including all such visible property values in document order).

While at first it may seem silly to create a name for something which is merely an address or a latitude+longitude geolocation, there are some good reasons to imply a name even for such collections of properties.

Locations are often shown in a list (e.g. by Checkin interfaces and applications). Lists showing all the locations on a page (e.g. all its h-card, h-adr, h-geo microformats) need labels for each item. The name of a location (whether explicit or implied) serves as the presentational label/title for that location in such lists.

Checkin location lists are just one use-case, there are many more. Any kind of page summarization tool (e.g. validators, linters) or anything which presents an interface to summaries of a page (e.g. web search results) benefits from having an explicit automatic way to determine how to label each and every microformat data item on a page.

Every such list of data items needs to label the items, and rather than just calling them "untitled item 1" etc., using the actual visible content of the item provides a nice clear connection to the specific item. Since the implied name comes directly from a snippet of text authored by a human, in the order that the human authored it as they intended it to be read (listened to), it will make sense as a label as well.

If an author explicitly wants an empty label for their microformat, while not recommended, they can explicitly specify as such: <span class="p-name"></span>

In practice this has yet to be seen, thus for now, any concerns about awkward or confusing implied names for things like h-adr or h-geo are categorized as a "theoretical issue". If someone finds a real world example where the implied "name" causes a bad user experience in some actual use-case, then we can re-explore this topic.

does microformats 2 combine vocabularies and syntax

Q: Does microformats 2 combine vocabularies and syntax?

A: No. From a parsing perspective, microformats 2 syntax is independent of any particular vocabulary. There are some microformats2-brainstorming proposals that take advantage of semantic HTML to imply certain common properties (name, url, photo) but that's an extremely limited set that's been determined from common markup patterns.

does microformats 2 split vocabularies and syntax

Q: Does microformats 2 split vocabularies and syntax?

A: Yes, microformats 2 specifies a syntax for parsing microformats which is independent of any specific vocabulary. So in that sense it can be said that microformats 2 splits vocabularies and syntax.

are microformats 2 vocabularies available to other languages

Q: Are microformats 2 vocabularies available to other languages?

A: Existing microformats vocabularies have profiles which are already available to other languages. Each term is defined by a URL ending in a hash and the term. This is due to the design of XMDP which deliberately produces such URLs which are compatible with microdata, RDF, and any other LinkedData system. microformats 2 vocabularies will use the same profile format and thus also be available to other languages.

how do you convert a microformats 2 example to RDFa syntax

Q: How do you convert a microformats 2 example to RDFa 1.1 syntax?

A: In short you have to use the 'typeof' attribute for the microformats 2 root class name, and use the 'property' attribute for microformats 2 properties.

E.g. this from the microformats 2 page:

<h1 class="h-card">
 <span class="p-name">
  <span class="p-given-name">Chris</span>
  <abbr class="p-additional-name">R.</abbr>
  <span class="p-family-name">Messina</span>

Here is the same markup with RDFa 1.1 syntax, using an implied or explicit RDFa Profile from somewhere else (undefined):

<h1 typeof="h-card">
 <span property="p-name">
  <span property="p-given-name">Chris</span>
  <abbr property="p-additional-name">R.</abbr>
  <span property="p-family-name">Messina</span>

The similarity of these two markup examples implies that it may be possible to extend RDFa 1.1 compliant parsers to become compliant microformats 2 parsers.

see also