Part IV: Enhancing hCard

The Challenge

We're marking up a real estate agent using Microformats. We have already finished an extensive hCard. Now on to learning some more advanced techniques!
The "Vocabulary"

We started out with the hCard microformat. There are some additional microformats we can use along with hCard, however!
- XFN
- rel-tag
The "Specification"

We are already using a microformat design pattern, the class-design-pattern, but there are some more we can learn!

Where we left off

<div class="vcard">
	<img src="photo.jpg" width="100" height="100" alt="" class="photo" />
	<div class="fn n">
		<span class="given-name">Janice</span>
		<span class="family-name">Smithington</span>
	</div>
	<div class="org">
		<span class="role">Real Estate Agent</span>
		<span class="title">Buyer's Agent</span>
		<span class="organization-name">Tepidpool Realty Brokerage</span>
	</div>
	<div class="adr">
		<span class="street-address">123 Address St.</span>
		<span class="locality">Citytown</span>,
		<span class="region">State</span>
		<span class="postal-code">33333</span>
		<div class="geo">
			<span class="latitude">30.38</span>
			<span class="longitude">84.37</span>
		</div>
	</div>
	<a href="http://www.homes.com" class="url">Website</a>
	<a href="mailto:test@example.org" class="email">E-Mail</a>
	<ul>
		<li class="tel">
			<span class="type">Work</span>
			<span class="value">(850) 333-2222</span>
		</li>
		<li class="tel">
			<span class="type">Home</span>
			<span class="value">(850) 222-6677</span>
		</li>
	</ul>
</div>

Notes

When we discussed the types of information we might have about a real estate agent, we mentioned "designations," but we did not add those to our hCard. As you might imagine, there is not a "designations" property in the hCard Microformat. What there is:
- note
Notes in an hCard can contain pretty much any related miscellaneous information about a person (or organization).
```
...
<div class="note">
	<ul>
		<li>SRES</li>
		<li>NUMBER1EXPERT</li>
	</ul>
</div>
...
```
Hidden Content

Sometimes you might want to display information on your website in a certain way for aesthetic reasons, but want to give a parser a more machine-friendly version of the same content. A phone number is a simple example. If your business is in the US only, it's unlikely you'd display phone numbers on your website using an international calling prefix. But when providing this information to a parser, it's best to be specific.

Using Design Patterns

There are some other microformat markup patterns that we can use to accomplish this.

value-class-pattern

The value-class-pattern uses variations of the class "value" to provide additional information about what the actual parsed value should be. In this first example we'll use the value-class-pattern to:
1. Provide a different phone number type to the parser. The valid phone types are restricted by the hCard format and may not match what you'd prefer to display.
2. Provide an international-format phone number to the parser, while displaying the number in a different way.
```
...
<ul>
	<li class="tel">
		<span class="type">
			<span class="value-title" title="pref work"></span>
			Days
		</span>
		<span class="value">
			<span class="value-title" title="+18503332222"></span>
			(850) 333-2222
		</span>
	</li>
	<li class="tel">
		<span class="type">
			<span class="value-title" title="home"></span>
			Nights
		</span>
		<span class="value">
			<span class="value-title" title="+18502226677"></span>
			(850) 222-6677
		</span>
	</li>
</ul>
...
```
value-class-pattern is relatively new and I have personally not tested its support in parsers.

abbr-design-pattern

The abbr-design-pattern uses the abbr tag to provide alternative versions of content. Here is the same example from above using the abbr-design-pattern.
```
...
<ul>
	<li class="tel">
		<abbr class="type" title="pref work">Days</abbr>
		<abbr class="value" title="+18503332222">(850) 333-2222</abbr>
	</li>
	<li class="tel">
		<abbr class="type" title="home">Nights</abbr>
		<abbr class="value" title="+18502226677">(850) 222-6677</abbr>
	</li>
</ul>
...
```
abbr-design-pattern has been criticized due to accessibility problems. A screen reader will always read aloud the title attribute. When using this pattern to hide alternate versions of content, this can be redundant and negatively affect user experience. It has decent support, though.
Nested Microformats

Nesting hCards

The hCard we're building is for a real estate agent. But some of our products are for offices and brokers. Plus, the office is often an entity independent of the agent. It's possible to nest hCards, so that when we mention an office affiliation, we also provide an hCard for the office.
```
...
<div class="org vcard">
	<span class="organization-name fn org">Tepidpool Realty Brokerage</span>
	<div class="adr">
		<span class="street-address">456 Mains St.</span>
		<span class="locality">Citytown</span>,
		<span class="region">State</span>
		<span class="postal-code">32333</span>
	</div>
</div>
...
```
When combining multiple microformats together, nesting is heavily utilized.
Including Microformat Data

Microformats are primarily good for marking up information that you already have on the page. But when you begin using them, you sometimes run into issues where the output you want to see doesn't match what you are using on the page. Sometimes that's related to different formats of the same information, like I covered earlier. Other times it's related to information not all being together on the page.

Take the example of the nested office above. What if you have an agent's contact information and their office's contact information on the same page, but they are very far apart? How can you express the relationship between them without nesting?

Assume you have this for the office:
```
<div class="vcard" id="office-vcard">
	<span class="fn org">Tepidpool Realty Brokerage</span>
	<div class="adr">
		<span class="street-address">456 Mains St.</span>
		<span class="locality">Citytown</span>,
		<span class="region">State</span>
		<span class="postal-code">32333</span>
	</div>
</div>
```
You can use the include-pattern to include this information elsewhere on the page, in your agent's hCard.
```
...
<div class="org">
	<span class="organization-name">Tepidpool Realty Brokerage</span>
	<a class="include" href="#office-vcard" title="More information about this organization">?</a>
</div>
...
```
There are some things to keep in mind about includes, however:
1. Only a few microformats specifically allow includes.
2. Includes are relatively new and I have not tested their parsing support.
The example I've used isn't specificially supported right now, though it's under consideration. Currently you can include hCards into hResumes and hReviews. Microformats become "accepted" in part through popular use -- aka "valid use cases." So although hCard doesn't specifically support includes, I plan on using includes anyway!
Combining Microformats

In addition to nesting microformats, we can also combine them. In the previous tutorial we briefly discussed this in regard to labeling the urls in an hCard if a person has more than one website.

Note: Upon re-reading hCard I feel it's more appropriate to say that the label is the a text and the actual "url" property value is the href. It's up to the parser to treat it this way, however, and the lack of "type" and "value" properties is still potentially troublesome.

XFN

The relationship of the link to the person can be expressed with XFN which is a microformat meant to describe connections and relationships between people through links. XFN makes use of the rel-design-pattern, which places the property in the rel attribute. (This is just a regular old HTML attribute that is not often used.)
```
<a href="http://www.facebook.com/me" class="url" rel="me">Facebook</a>
```
Unfortunately XFN doesn't currently support connections between organizations, so there is currently not a valid value for, say, "employer." (I think that you could express this with nesting and includes, however. Or just start using it; if enough people think it's useful it will probably make it into a specification.)

rel-tag

Remember when we added designations earlier as an hCard note? We can also use rel-tag to enhance designations. rel-tag is a little odd. It's a microformat itself and it's intended to associate tags with a page -- or with someone/something being described using another microformat. The tags are always expressed as links. If being used on a blog it would link to the page of the blog that shows all posts associated with the tag. If being used in a situation where there is no such internal page, however, you can link it to an external site that defines the tag -- like this Technorati page or this Wikipedia article.

This can be used to enhance our designations by making the designations into tags:
```
...
<div class="note">
	<ul>
		<li><a href="http://en.wikipedia.org/wiki/Seniors_Real_Estate_Specialist" rel="tag">SRES</a></li>
		<li><a href="http://www.number1expert.com/WhyChoose/" rel="tag">NUMBER1EXPERT</a></li>
	</ul>
</div>
...
```
hResume

hResume uses nested or included hCards to refer to the person and their employers.

hReview

hReview uses nested or included hCards or hCalendar events to refer to the reviewer and the reviewee.

hListing

hListing uses nested hCards to refer toward the person listing the item for sale. This is what we'll be looking at next week!

Viewing & Debugging

hCard using value-class-pattern

Janice Smithington

Tepidpool Realty Brokerage ?

123 Address St. Citytown, State 33333

30.38 84.37

Facebook E-Mail

Days (850) 333-2222
Nights (850) 222-6677

hCard for an organization (used for includes)

Tepidpool Realty Brokerage

456 Mains St. Citytown, State 32333

hCard using abbr-design-pattern

Janice Smithington

Real Estate Agent Buyer's Agent

Tepidpool Realty Brokerage ?

123 Address St. Citytown, State 33333

30.38 84.37

Facebook E-Mail

Days (850) 333-2222
Nights (850) 222-6677

<div class="vcard">
	<img src="photo.jpg" width="100" height="100" alt="" class="photo" />
	<div class="fn n">
		<span class="given-name">Janice</span>
		<span class="family-name">Smithington</span>
	</div>
	<div class="note">
		<ul>
			<li><a href="http://en.wikipedia.org/wiki/Seniors_Real_Estate_Specialist" rel="tag">SRES</a></li>
			<li><a href="http://www.number1expert.com/WhyChoose/" rel="tag">NUMBER1EXPERT</a></li>
		</ul>
	</div>
	<span class="role"><a href="http://en.wikipedia.org/wiki/Real_estate_broker/agent" rel="tag">Real Estate Agent</a></span>
	<span class="title"><a href="http://en.wikipedia.org/wiki/Real_estate_broker/agent#Services_provided_to_buyers" rel="tag">Buyer's Agent</a></span>
	<div class="org">
		<span class="organization-name">Tepidpool Realty Brokerage</span>
		<a class="include" href="#office-vcard" title="More information about this organization">?</a>
	</div>
	<div class="adr">
		<span class="street-address">123 Address St.</span>
		<span class="locality">Citytown</span>,
		<span class="region">State</span>
		<span class="postal-code">33333</span>
		<div class="geo">
			<span class="latitude">30.38</span>
			<span class="longitude">84.37</span>
		</div>
	</div>
	<a href="http://www.facebook.com/me" class="url" rel="me">Facebook</a>
	<a href="mailto:test@example.org" class="email">E-Mail</a>
	<ul>
		<li class="tel">
			<span class="type">
				<span class="value-title" title="pref work"></span>
				Days
			</span>
			<span class="value">
				<span class="value-title" title="+18503332222"></span>
				(850) 333-2222
			</span>
		</li>
		<li class="tel">
			<span class="type">
				<span class="value-title" title="home"></span>
				Nights
			</span>
			<span class="value">
				<span class="value-title" title="+18502226677"></span>
				(850) 222-6677
			</span>
		</li>
	</ul>
</div>

The Challenge

The "Vocabulary"

The "Specification"

Where we left off

Notes

Hidden Content

Using Design Patterns

value-class-pattern

abbr-design-pattern

Nested Microformats

Nesting hCards

Including Microformat Data

Combining Microformats

XFN

rel-tag

hResume

hReview

hListing

Viewing & Debugging

hCard using value-class-pattern

hCard for an organization (used for includes)

hCard using abbr-design-pattern